eust-w b47a07e8d2 chore: baseline snapshot of the Codex-delivered code before review
Imports the previously untracked working tree as-is so that the review
changes that follow (requirements -> design -> implementation) can be
reviewed as diffs and reverted if needed. No content changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 13:18:04 +08:00
..

Workspace coordination engine

require('./index.cjs') exports Coordinator and CoordinationError. It uses only Node built-ins. Run node --test apps/ide/coordination/test/*.test.cjs from the repository root.

Create one coordinator per workspace backend with new Coordinator({ workspaceRoot, stateDirectory, now?, limits? }). Both paths and optional limits come from trusted provisioning configuration. The state directory must be outside the source tree, on the same local filesystem throughout the backend's lifetime, and should be inaccessible to workspace writers in a hardened deployment. The current Theia integration runs backend and terminal under the same UID, so that privilege separation is not provided by a separate directory or PVC. Its own and its object/manifest directory modes are 0700, which does not exclude same-UID terminal processes. The engine never writes source files or overwrites editor drafts.

The caller must authenticate each RPC/HTTP request and supply actorId from its trusted session. These methods do not authenticate an arbitrary actor string. Only authorized workspace participants should receive state or call methods. revoke(actorId) removes the actor's registered clients, invalidates affected pending barriers, and destroys its debug lease; gateway ACL enforcement must also reject subsequent calls and close revoked connections.

Save barrier API

  • register(actorId, clientId, { documents: [{ uri, version, dirty }], dirty? }) registers/heartbeats a tab. Heartbeats expire after 30 seconds. A client ID cannot change actor. File URIs must be inside the workspace; relative paths are normalized. Other editor URI schemes are opaque document IDs and are never read as filesystem paths. All dirty editors, including unsaved untitled buffers, must be reported.
  • unregister(actorId, clientId) removes only the caller's tab and invalidates barriers containing that tab, preserving the actor's other tabs. Invoke it on connection close.
  • beginBarrier(actorId) requires an active client of the creator and freezes active clients, their document version vectors, and a digest of disk content. Returns { id, actorId, status, expiresAt, diskDigest, participants }. Only one pending barrier is allowed, with a 30-second deadline.
  • acknowledge(actorId, barrierId, clientId, payload) accepts only that client's authenticated actor. The caller invokes the editor's saveAll, reports its full clean vector via register, then acknowledges with the same vector. All participants must acknowledge; no coordinator or other actor can acknowledge on their behalf.
  • await commitBarrier(actorId, barrierId) is restricted to the creator. It rejects unacknowledged, expired, dirty, changed-version or revoked participants. New clients or edits invalidate a pending barrier. Disk changes since barrier creation also invalidate it, so if saving changed disk the caller starts a fresh barrier after all saves complete. Retrying a committed barrier returns the same snapshot and revision, including after restart. Every client must register again before participating in new barriers after backend restart.

Commit returns { schemaVersion: 1, id, revision, previousId, workspace, digest, files: [{ path, sha256, size, mode }], createdAt, actorId, barrierId }. It snapshots regular files under the configured root, rejects symlinks and special files, and excludes generated/runtime directory names .git, node_modules, dist, build, coverage, .next, .cache, src-gen, .wishforge, .wishforge-runtime, .runtime, .coordination. These names are excluded at any depth. New project-specific generated paths require explicit policy updates, not a client-supplied arbitrary path list.

Resource caps default to limits: { maxFileBytes: 33554432, maxTotalBytes: 268435456, maxFiles: 20000 } (32 MiB per file, 256 MiB total and 20,000 files). Overrides must be positive safe integers and cannot come from editor RPC input. Scans reject over-limit source with SNAPSHOT_LIMIT before opening the offending file, recheck the open descriptor's size, and read only the validated bounded length so concurrent growth cannot cause an unbounded allocation. Total bytes count every included path, including duplicate content; empty files count toward maxFiles. Excluded runtime paths consume no quota. Begin and final verification scans do not retain content blobs. Immediately after the final scan, commit rechecks barrier expiry and all participant heartbeats, acknowledgement, clean state and version vectors; elapsed scanning time does not extend the 30-second deadlines.

Each manifest refers to SHA-256-addressed blobs in objects/. Manifests and blobs are created without replacement and made read-only; the journal head is atomically replaced and fsynced. Recovery verifies the manifest chain and referenced content and reconstructs the head if a crash occurred after the immutable manifest commit but before the journal update. Partial temporary files and unreferenced blobs are not committed snapshots. Corruption fails closed. This is a local filesystem integrity proof, not production immutable storage, an OS-level filesystem freeze, or a guarantee against a privileged process rewriting state. External filesystem writers must also be gated by the caller; the engine detects changes with two full content scans but cannot lock arbitrary external writers.

Debug controller API

  • debugAcquire(actorId) returns { actorId, token, expiresAt }; only one live lease exists and its token has 256 bits of randomness.
  • debugAcquire(actorId, token) renews the current lease for 30 seconds. A same-actor caller without the token cannot silently take over another tab.
  • assertDebugController(actorId, token) must guard every mutating debug request, not just the UI buttons. It validates owner, token and expiry.
  • debugTransfer(actorId, token, targetActorId) requires an active registered target and rotates the token. The trusted backend must deliver the new token only to the target actor's connection.
  • debugRelease(actorId, token) releases ownership. state() exposes controller owner/deadline, never the token.

Client membership, barriers and debug leases are intentionally ephemeral. A restarted backend requires fresh registration and debug acquisition, so old tokens or acknowledgements cannot authorize new actions. Durable state is the verified snapshot revision chain and exact saved contents. Only one active backend should own a workspace; the local writer lock guards commit/recovery operations, not distributed live membership. The backend integration is responsible for periodic heartbeats, save requests to all participants, and sending updated state.

The current backend integration is a cooperative-client control, not an adversarial terminal sandbox. A same-UID terminal can tamper with writable state or replace the backend; a hardened deployment needs a separately privileged coordination service reached directly through the gateway and independently controlled debugger processes. Workspace snapshots are not independent release evidence.