📝 Specify retained workflow Workspaces

[taras]

Why

The Workspace design evolved across #218, #346 and three implementation spikes, but its accepted decisions existed only in issue comments and a local interview transcript. The old #218 contract still assumed an explicit Cloudflare Workspace whose persistence was separate from the journal, which no longer matched the selected topology or the intended Agent authority model.

What changes

Before:

The architecture stopped at workflow-run identity and base pinning. Replay restoration, lifecycle commands, repository composition, local transaction boundaries, history forks, Agent authority and the Deno/DOFS topology were unresolved or described inconsistently across issues.

After:

The architecture defines the retained implicit Workspace and its invariants. A new specification records the observable xmd workflow contract, from the first command and multi-repository examples through replay, failure, history and topology.

How it works

immutable workflow definition
        → WorkflowRun + implicit Workspace
        → one expansion / one effect / one local transaction
        → filtered journal result + versioned Workspace root
        → replay, resume or explicit history fork

The local host owns SQLite in Deno and uses Cloudflare DOFS behind contextual APIs. Workspace-local filesystem, Git and metadata effects commit their mutation and journal result atomically. External Agent, Push and PullRequest effects reconcile stable identities instead. Agents receive read-only materializations and propose constrained XMD for the durable evaluator to execute.

Review guide

Start with: architecture.md, from “Workflow Workspace” through “Local Workspace topology”

Then review:

1. specs/workflow-workspace-spec.md §§1–4 for command, identity and lifecycle behavior
2. §§5–8 for Repository, Worktree, Git and read-only Agent composition
3. §§9–12 for replay, transaction, fork and retention contracts
4. §§13–14 for the evidence-backed local topology and implementation inventory

Look carefully at:

• the distinction between the workflow definition repository and Repositories created inside the Workspace;
• the one-expansion/one-effect/one-transaction boundary;
• the rule that ephemeral replay rebuilds context but never owns durable state;
• external-effect ambiguity and history-fork limits; and
• the mandatory read-only Agent ceiling and generated-XMD allowlist.

What must stay true

• PR 💥 Add expansion identity and pinned-commit workflow runs #341's run and expansion identities remain the foundation; a WorkflowRun definition base never becomes an implicit Workspace Repository.
• xmd run retains current-environment semantics; durability belongs to xmd workflow.
• Completed replay does not attach Workspace, Agent or external providers.
• Partial replay reattaches the same authoritative Workspace; it never reconstructs history from frontier file existence.
• Journal filtering remains the persistence boundary for retained history and future training ingestion.
• Worker Shell requires the transaction routing, rollback, fencing and forceful cancellation proven by Spike: make Worker Shell effects transactional with the workflow journal #357 / PR 🔬 Spike: make Worker Shell effects transactional (#357) #362.

How to verify it

• git diff --check verifies that both Markdown changes are free of whitespace errors.
• Read the first workflow, multi-repository Agent example, replay table and transaction pseudocode as one path; they must describe the same component and authority behavior.
• No source or test files change, so the runtime verification suite is not applicable to this documentation-only design PR.

Scope

Included

• terminology for Workspace, ephemeral operations, effect transactions, external effects, checkpoints and history forks;
• foreground workflow lifecycle and inspection commands;
• implicit Workspace, Repository, Worktree, Git and Agent composition contracts;
• replay, restoration, local atomicity, external reconciliation and fork semantics;
• Deno-local SQLite/DOFS topology and the initial Worker Shell boundary; and
• updated construct inventory.

Intentionally unchanged

• runtime implementation of every newly specified construct;
• the public name and final schema of the generated-XMD evaluator (<Expand> is a placeholder);
• Worker JavaScript, native process execution, writable FUSE and bundled workerd in the initial local host;
• a public remote-host selector; and
• the existing journal security-filtering implementation.

New abstractions

• The Workspace and effect-transaction terms name concrete boundaries consumed by filesystem, Git, lifecycle and Agent implementations.
• Each new abstraction has multiple concrete uses or a clear justification.
• No speculative functionality is included.

Risks and limitations

• This PR deliberately records a broad product contract before implementation. Child issues still need to sequence it without weakening its transaction or authority boundaries.
• Worker Shell is included on the strength of Spike: make Worker Shell effects transactional with the workflow journal #357 / PR 🔬 Spike: make Worker Shell effects transactional (#357) #362, but production must preserve its single authoritative DOFS connection, transaction fencing and forceful Worker termination constraints.
• Provider-owned Agent state and external Git/forge effects cannot share the local SQLite transaction, so their providers must support the specified reconciliation or fail explicitly.

Closes #346. Defines the implementation contract for #218 and updates the path to #181.

Scope confirmation

• Every changed file supports the purpose described above.
• Unrelated cleanup and formatting changes are excluded.
• Generated or mechanical changes are clearly identified.
• The description matches the final diff and test results.

[github-actions]

PR #358: 📝 Specify retained workflow Workspaces

2 files, +955 / -9

Scope

🔴 PR has 964 lines changed. Split into focused PRs.

🟡 964 lines changed. PRs under 400 receive more thorough review.

Structural

✅ No structural bloat detected.

Slop

✅ Slop indicators look low.

Static Analysis

✅ Oxlint found no issues.

Correctness

No extraneous code patterns detected.