Memory
# Work Engineering in the Workspace DO (Design Direction) **Date:** 2026-09-08 **Status:** Design direction, not yet implemented **Related:** Work Engineering Map v0 (server.js, client.js, README.md, RUN_RECORD.md), Sphere Starter, Cloudflare Computer workspaces, Artifacts, FTS5, callsigns as operators ## Core thesis A workspace DO is a self-contained work environment. Its Artifacts tree defines the work engineering map. The DO projects that map into active Workstations, each of which exposes a contract-governed subset of the workspace's primitives to a named Operator working on a Lot. ## Architectural model ### Workspace DO The Cloudflare Computer workspace DO is the runtime unit. It provides: - File/directory primitives (skills/, documents/, evidence/, gadgets/, work/) - MCP tool surface - Sandbox / code execution - Callsign identity for operators - Coordination for multi-agent work - Artifacts binding for versioned storage - SQLite + FTS5 for indexed queryability ### Work Engineering Database The work engineering "database" lives primarily as a **versioned Artifacts tree** inside the workspace DO: ``` /work/ manifest.json # Canonical work map (or work-map.json) ontology.json # Types, allowed relations, vocabularies objects/ # Work Object definitions routings/ # Work Process (Routing) definitions workstations/ # Workstation definitions contracts/ # Contract definitions operators/ # Operator/callsign profiles runs/ # Active Lot state evidence/ # Evidence records per Lot/Workstation ``` Key principles: - **Artifacts-first:** canonical, versioned, Git-compatible storage - **JSON/Markdown as authority:** not relational tables (initially) - **FTS5 as derived index:** rebuildable from Artifacts, not authoritative - **DO runtime state:** active operators, workstation sessions, locks, caches ### Workstation as capability projection A Workstation is **not** just a database record. It is: > A projection of the workspace's available primitives, governed by a Contract, for a specific operation in a Routing. **Workspace primitives** might include: - read_file, write_file, list_files - run_code, call_model, call_external_tool - read_artifact, write_artifact - search_fts, record_evidence **Workstation definition** (in Artifacts) specifies: - Which primitives are exposed - Which directories/buckets are accessible - Which contract governs the operation - Input/output Work Objects - Quality requirements (if a quality Workstation) - Operator assignments (callsigns) **Active Workstation** (runtime): - Created when an Operator claims a Workstation for a Lot - Exposes only the allowed methods/capabilities - Enforces contract rules at invocation time - Records outcomes and evidence to Artifacts - Advances the Lot when work is complete ### Callsign as Operator A callsign (e.g. `@docucleardev`, `@ingestion-op`, `@reviewer`) is: > The identity of an agent operating a Workstation. Not "assigned to a task", but **operating a Workstation** in a Routing for a specific Lot. This aligns with the SAP QM / work engineering model: - Callsign ≈ work center operator / production operator - Operator binds to Workstation, not to abstract "task" - Multiple Lots can share the same Workstation type with different Operators ### Lot-centric execution A Lot is a run-instance of a Routing for a Work Object. Execution flow: 1. Lot created from Routing + Work Object 2. Lot starts at first Workstation in Routing 3. Operator claims Workstation (callsign binds) 4. DO exposes Workstation capabilities to Operator 5. Operator performs work, invokes Workstation methods 6. Outcomes + evidence recorded to Artifacts 7. Lot advances to next Workstation 8. Repeat until Routing complete or blocked by quality gate ### Contract/Evidence Loop Each Workstation operates under a **Contract**: - Inputs (Work Objects) - Outputs (Work Objects) - Rules / constraints - Evidence requirements Every operation produces **Evidence**: - Run records - Outcomes - Quality characteristics (for quality Workstations) - Decision traces (approvals, rejections, rework) This preserves the "every merge reconstructible / every yes reconstructible" property from the earlier loop design. ## Key design rules (preserved from Work Engineering Map v0) From the validated v0 implementation (server.js, README.md, RUN_RECORD.md), preserve these behavioural invariants: 1. **Typed domain verbs** — no generic CRUD, only meaningful operations 2. **Definitions vs instances** — Routings/Workstations are reusable; Lots are per-run 3. **Quality independence** — only quality Workstations own Characteristics 4. **Gate direction** — failed gates block, never auto-advance; blocked routes to human 5. **Evidence discipline** — inputs must exist as recorded Work Objects; gate outcomes cite contracts + evidence 6. **Revision + supersession** — history preserved, no silent overwrite 7. **Stable error responses** — all errors returned as data, never silent voids 8. **Brief/report surface** — agent can always inspect current state + next actions ## Proposed API surface (illustrative) ```text getWorkBrief() # Current state summary, next actions readDefinition(id) # Read a Work Object/Routing/Workstation/Contract searchWork(query) # FTS5-backed search over work definitions startLot(input) # Create new Lot from Routing + Work Object claimWorkstation(lotId, workstationId, callsign) # Bind operator to workstation getActiveWorkstation(lotId) # Get current active workstation for a lot invokeWorkstation(method, input) # Execute workstation method (contract-governed) recordEvidence(input) # Append evidence record evaluateQuality(input) # Evaluate quality characteristic (quality workstations only) advanceLot(lotId) # Advance lot to next workstation (if gates pass) inspectArtifact(path, rev?) # Read artifact from Artifacts tree (optionally historical) ``` Key principle: agent does not call raw primitives directly. Agent calls Workstation methods, which the DO resolves, governs, and records. ## Implementation notes ### Artifacts + SQLite + FTS5 Three-layer storage: 1. **Artifacts repo** — authoritative, versioned source of truth - work-map.json (or manifest.json) - Individual entity files (optional, as complexity grows) - Evidence files (JSONL or JSON) - Every update = commit with metadata (operator, timestamp, contract version) 2. **SQLite** — fast structured queries over current state - Normalized views of Work Objects, Routings, Workstations, Contracts, Lots - Updated on every Artifacts commit 3. **FTS5 virtual table** — BM25 keyword search - Indexes workstation names, contract descriptions, evidence metadata, etc. - Rebuildable from Artifacts if lost ### Operator sessions The DO tracks: - Active operator sessions (callsign + workstation + lot) - Locks (prevent concurrent conflicting operations) - Temporary execution state (e.g. in-progress code runs) ### Capability enforcement When a Workstation is activated: - DO reads Workstation definition from Artifacts - Validates Contract exists and is pinned - Checks Operator (callsign) is authorized - Exposes only the allowed methods/capabilities - Records session start to Artifacts On each method invocation: - Verify session is active - Verify method is allowed for this Workstation - Enforce contract rules (inputs exist, outputs valid) - Execute method (code, model call, file operation, etc.) - Record outcome + evidence to Artifacts - Update Lot state ## Open questions / decisions 1. **Single manifest vs multiple files** — Start with `work-map.json`, split only when needed? 2. **Operator authorization** — How are callsigns authorized for specific Workstations? (Contract-governed, or DO-level ACL?) 3. **Multi-agent coordination** — How do multiple callsigns coordinate on the same Lot? (AgentSphere layer, or DO-native?) 4. **Contract pinning** — How are contract SHAs pinned and verified? (Reference to `int_contracts`?) 5. **Evidence granularity** — One file per Lot, per Workstation, or per operation? 6. **FTS5 scope** — Index only definitions, or also evidence content? 7. **Blueprintability** — How does this become a reusable blueprint for customer workspaces? ## Next steps 1. **Define minimal work-map.json schema** — Work Objects, Routings, Workstations, Contracts, Operators 2. **Implement Artifacts sync** — Commit/retrieve work definitions as JSON 3. **Build SQLite + FTS5 index** — Derived from Artifacts, rebuildable 4. **Implement capability projection** — Active Workstation runtime in DO 5. **Dogfood with one flow** — e.g. Ingest → Transcribe → Review (meeting audio use case) 6. **Document operator experience** — How does a callsign actually work in this model? ## References - Work Engineering Map v0: server.js, client.js, README.md, RUN_RECORD.md (attached files) - Sphere Starter: Cloudflare Computer workspace with skills/, documents/, evidence/, gadgets/ - Mini-Sphere contract draft (SQLite + FTS5 in DO) - Contract/Evidence Loop (four artifacts, three checks) - TotalDB (12-table Work Engineering schema as alternative substrate) - Cloudflare Artifacts (Git-compatible versioned storage on DOs) --- **Note:** This is a design direction, not an implementation spec. The actual build may diverge as the workspace DO architecture is explored.
Tags: work-engineering, sphere-starter, workspace-do, artifacts, fts5, callsigns, operators, workstations, contracts, design-direction, volatility:state, duplicate-candidate, kind:semantic — Source: mcp — 2026-09-08 22:21:23 UTC