Workspace files
Workspace files provide each authenticated user with a folder hierarchy for notebooks, Markdown, CSV, and other uploaded objects. Users can browse, create, open, save, rename, move, clone, download, share, trash, restore, and inspect file history according to their effective permissions.
See Architecture, evidence and reproduction, and component references.
Assessment scope
| Field | Value |
|---|---|
| Actors | Workspace user, collaborator, workspace administrator, and platform operator |
| Components assessed | sparqd/oqullus, sparqd/bff-api, sparqd/workspace-file-management-backend, PostgreSQL, S3 or OSS, and sparqd/platform-stacks |
| Assessed environment | Realm gj76anadpsc; workspace w-t5e2kcxjd; Kubernetes context dev-north-alicloud |
| Assessed baselines | Oqullus integration source f76e57dbb88d; deployed BFF API 9b2fd45a4da1; deployed workspace-file backend 5dcbb222241b; platform-stacks a71390d12463 |
| Newer backend reviewed | f82d4cc7ad1f; not deployed in the assessed workspace |
| Last verified | 4 September 2026 |
| Review status | Engineering assessment recorded; product, security, and operations validation not yet recorded |
Notebook execution and kernel state are assessed separately. This assessment covers the file object and folder lifecycle, ACLs, storage, browser behavior, history, recovery, failure handling, and scale boundaries. Dashboard and saved SQL-query persistence are excluded because they use other resource models.
Conditions for the assessed path
- The user is authenticated in the workspace and the BFF can exchange a token for the workspace-file backend audience.
- PostgreSQL and the configured workspace S3 or OSS bucket are reachable.
- Create, upload, edit, rename, and move require effective Editor or Maintainer access; share and delete require Maintainer access.
- Sharing targets direct users only. Group sharing is not part of the current contract.
- The live evidence covers the AliCloud OSS deployment. AWS S3 behavior is source-backed through the alternate storage adapter, not a claim of identical deployed evidence.
- Version History in
w-t5e2kcxjdis activity metadata, not content recovery, untilREL-WSF-001is closed.
Current capability boundary
| Capability | Current state | Boundary |
|---|---|---|
| Browse folders | Available | Folder and shared-item responses are unpaginated |
| Create folders and files | Available inside a selected folder | Root-page actions use the wrong response field and can fail to resolve the user's root |
| Open and edit | Notebook, Markdown, and CSV paths are recognized | Other file types are storage/download objects; type presentation is inconsistent |
| Save | Available through full-object replacement | No optimistic concurrency; see REL-NB-006 in the notebook assessment |
| Rename and move | Available with stable public IDs | Folder move validation is authoritative in the backend; the client tree is only advisory |
| Clone | Files only | Folder copy is not implemented |
| Upload | Multiple files accepted | Full files traverse browser, BFF memory, and backend; no explicit size or concurrency boundary |
| Download | Files only | Full content traverses backend and BFF and becomes a browser Blob although a direct resolve endpoint exists |
| Share | Direct user grants with viewer, editor, or maintainer role | No group grants; copied list-view link is invalid; member selection is limited to the first 100 account members |
| Trash and restore | Soft delete, restore, and permanent delete exist | Destination is inferred and may be silently changed after failure; Trash paging, conflict recovery, cleanup deployment, and retained object versions are incomplete |
| History, diff, and revert | UI and API are exposed | Not operational in w-t5e2kcxjd: 173/173 history rows lack an object-version ID; diff can falsely succeed by comparing current content to itself, and View Changes ambiguously means selected-versus-newest rather than the change introduced by a revision |
| Search | Backend file search exists | The visible search only filters the currently loaded folder; backend search is unused by Oqullus |
| Favorites | UI is exposed | React-state only; it disappears on navigation or reload and has no backend model |
Critical journeys
| Journey | Required result |
|---|---|
| Browse and open | Show only authorized children and distinguish an empty folder from a failed request |
| Create and upload | Resolve the intended parent, enforce limits, report each file independently, and avoid duplicate or orphaned objects |
| Save and concurrent edit | Reject stale writes or provide explicit conflict recovery |
| Rename and move | Preserve canonical identity, open tabs, inherited access, and valid paths |
| Share and open link | Grant the intended resource and produce an authenticated canonical deep link |
| Unauthorized access | Deny metadata, content, history, and workflow output without leaking resource data |
| Large transfer | Keep BFF and browser memory bounded and expose progress, cancellation, timeout, and retry |
| Delete and restore | State retention, restore target, conflicts, and permanent deletion truthfully |
| History and revert | Retain retrievable content versions and prove a selected version can be restored |
| Backend or storage failure | Preserve visible prior state, identify partial completion, and offer a safe retry |
| Large folder or workspace | Page and filter before materializing the complete authorized result set |
Findings
Each linked finding contains the concrete case, expected condition, alternatives, component involvement, reproduction, and closure conditions.
| ID | Finding | Components | Evidence | Impact |
|---|---|---|---|---|
SEC-WSF-001 | Authorize workflow output notebooks against the selected run | Workspace file backend, workflow authorization, BFF API | Source-verified | Critical |
REL-WSF-001 | Make exposed history, diff, and revert recover content | Workspace file backend, platform-stacks, object storage, Oqullus | Live aggregate + source | Critical |
DATA-WSF-001 | Reconcile PostgreSQL metadata with object-storage mutations | Workspace file backend, object storage | Source-verified | High |
DATA-WSF-002 | Key roots and ACLs by an immutable identity subject | Workspace file backend, identity/account services, Oqullus | Source-verified | High |
PERF-WSF-001 | Bound upload and download memory and concurrency | Oqullus, BFF API, workspace file backend, object storage | Source-verified | High |
PERF-WSF-002 | Page and authorize before materializing lists | Workspace file backend, BFF API, Oqullus | Source-verified | High at scale |
OPS-WSF-001 | Protect workspace metadata capacity and recovery | Platform stacks, KubeBlocks PostgreSQL, workspace file backend | Source-verified | Critical recovery boundary |
UX-WSF-001 | Use one root response contract for root actions | Oqullus, BFF API, workspace file backend | Source-verified | High |
PROD-WSF-001 | Hide or complete Search and Favorites | Oqullus, workspace file backend | Source-verified | Medium |
UX-WSF-002 | Share the selected resource with a canonical deep link | Oqullus, BFF API, workspace file backend | Source-verified | High |
REL-WSF-002 | Do not present request failure as empty state | Oqullus, BFF API | Source-verified | High |
REL-WSF-003 | Report partial multi-file upload outcomes | Oqullus, BFF API, workspace file backend | Source-verified | Medium |
REL-WSF-004 | Fail closed when historical diff content is unavailable | Workspace file backend, object storage, Oqullus | Source + live data shape | High |
UX-WSF-003 | Require the user to confirm restore destination and name | Oqullus, workspace file backend, BFF API | Source-verified | High |
UX-WSF-004 | Separate changes introduced by a revision from comparison with current | Oqullus, workspace file backend | Source-verified | Medium |
LIFE-WSF-001 | Operate trash and object-version retention end to end | Workspace file backend, platform-stacks, object storage | Live deployment + source | High |
PROD-WSF-002 | Define supported file types consistently | Oqullus, workspace file backend | Source-verified | Medium |
Findings are observations, not accepted implementation commitments. Open design and validation work remains explicit in each finding.
Interim workarounds
- Enter the user's root folder before creating or importing an item.
- Treat Version History as metadata-only in
w-t5e2kcxjd; keep an external copy before destructive edits because diff and revert cannot retrieve prior bytes. - Avoid simultaneous edits and large uploads. Upload files individually and refresh after any mixed success or failure.
- Open shared resources from the Workspace tree. Do not rely on the link copied by the list-view Share dialog.
- Refresh before concluding a folder, Trash, or permission list is empty after a request error.
- After Restore, locate the item and verify its parent; the current client can retry a different destination after the first request fails.
- Use folder-local search as a filter only; it is not workspace-wide search.
Assessment maturity
Scale: 0 absent, 1 ad hoc, 2 partly documented or automated, 3 routinely verified, 4 measured and improving.
| Lens | Score | Evidence-backed assessment |
|---|---|---|
| Product and UX | 1 | Core operations exist, but root actions, sharing identity, Search, Favorites, file types, and failure states are inconsistent. |
| Architecture and data | 1 | Canonical IDs and ACL inheritance exist; history bytes and cross-store consistency are not assured. |
| Security and privacy | 1 | File/folder ACL enforcement exists; workflow output authorization has a source-confirmed gap and lacks controlled validation. |
| Infrastructure and operations | 1 | Two API replicas and one PostgreSQL replica are deployed; database recovery, cleanup, lifecycle enforcement, reconciliation, and operation metrics are not established for this feature. |
| Reliability and performance | 1 | Small happy paths work; transfer and listing limits are neither enforced nor measured, and partial failure recovery is incomplete. |
| Delivery, cost, and lifecycle | 1 | Exact deployed commits are recorded; storage retention, capacity boundaries, reviewer decisions, and ongoing verification are open. |