Workspace

The workspace is a drive-like tree of files and folders, scoped per namespace, where every file write produces a new immutable revision in an append-only chain. Mutations use optimistic concurrency control (OCC) — you pass the version you think you’re editing, and a stale guess is rejected with a conflict instead of silently overwriting.

The drive tree

A WorkspaceItem is either a file or a folder (src/workspace/types.ts:6-9). Folders nest via parent_id, so items form a tree inside one namespace. Each item carries a monotonic version (starts at 1, types.ts:16) and, for files, a pointer to the latest revision:

Field	Meaning
kind	file or folder
namespace	the drive this item lives in
parent_id	enclosing folder (absent = root)
version	OCC counter, bumped on every item mutation
current_revision_id	latest revision (files only)
current_revision_number	revision count (files only)
deleted_at / deleted_by	set on soft-delete; IDs and history preserved

Deletes are soft — workspace.delete_item soft-deletes the whole subtree, preserving IDs and revision history (workspace.ts:295-313).

Immutable revisions

A file’s content lives in WorkspaceRevision rows, not on the item. Each revision is written once and never mutated (types.ts:36-47): it has a revision_number, a previous_revision_id linking it to its predecessor, a storage_key pointing at the backing blob, and size_bytes / content_type. Writing a file appends a new revision and re-points current_revision_id; the old revision stays addressable. workspace.list_revisions (HTTP GET /workspace/items/:id/history) walks the chain.

Text content is gated by isTextContentType (src/workspace/utils.ts:18-27) — only text/* plus json/javascript/typescript/xml/yaml/markdown content types go through the text read/write commands (workspace.read_text / workspace.update_text). Anything else is binary.

Optimistic concurrency (OCC)

There are two OCC tokens, one per kind of mutation:

• Item mutations (update_item, move_item, delete_item) require expected_version (workspace.ts:120-134). The store compares it to the item’s current version; a mismatch returns a conflict result, surfaced as HTTP 409 (workspace.ts:75-85,257).
• Text writes (update_text) require expected_revision_id — the id of the revision you read (workspace.ts:145,176). If a concurrent write moved the head, you get a revision conflict (409, workspace.ts:414,517).

read item v3 ──► edit ──► update_item(expected_version: 3)
                                   │
            head still v3 ─────────┼──► ok, item → v4
            head now v4   ─────────┴──► 409 conflict (re-read, retry)

The mutation result is a discriminated union — ok | not_found | conflict | deleted (types.ts:102-112) — so callers can branch on the outcome rather than catching an exception for the expected-version case.

Binary uploads use multipart or a local descriptor

Raw binary request bodies enter Chorus through the HTTP multipart routes (POST /workspace/files/upload, PUT /workspace/files/:id/content — src/workspace/routes.ts). Standalone local/stdio MCP and CLI shims can instead open a caller-supplied host path through one bounded regular-file descriptor and forward those bytes through the same object-storage lifecycle. The path-taking tools are omitted from shared HTTP MCP. The embedded /mcp surface never exposes host-path tools.

Both paths ultimately call the internal-only catalog ops workspace.create_file_record / workspace.write_revision_record, which are not exposed over RPC or MCP (gap-3 §1.7). The public catalog/JSON-RPC workspace.create_file operation accepts only text-like UTF-8 content; there is no JSON/RPC raw-binary body path.

Every binary upload path has an effective per-file ceiling

The HTTP multipart routes enforce getWorkspaceMaxSizeBytes() (ARTIFACT_MAX_SIZE_MB, default 50 MiB) and return 413 on overflow (routes.ts:127-129,208-210). Standalone MCP and CLI enforce the local descriptor ceiling first, then the receiving HTTP route enforces the workspace ceiling.

CHORUS_LOCAL_UPLOAD_MAX_BYTES defaults to 50 MiB and may be configured from 0 to 1 GiB, but increasing it cannot bypass the server’s workspace cap. For non-admin callers, the namespace quota is an additional bound. JSON text creation is bounded separately by the JSON transport body limit and namespace quota; it is not a binary-upload escape hatch.

The same op has different names per transport

A from-scratch reader will see one operation under several names: e.g. creating a text file is POST /workspace/files (HTTP), workspace.create_file (catalog), workspace/create_text and workspace.create_file (RPC), and workspace_create_text / deployed chorus_workspace_create_text (MCP). This naming drift is real (gap-3 F5) — match on the operation, not the literal name. See The command catalog.