🍴 Continue one run's history under a changed definition

`xmd workflow fork <source> --at=<event> <definition>` creates a new
immutable run whose journal begins as somebody else's. It writes two
records for itself — its own `workflow_run`, and its own root import,
which is what makes it a run of the definition the caller named — and
inherits everything after them with their public event ids, filtered
results, authored positions, Workspace roots and source provenance.

Compatibility is proved before any storage the host would recognize as
the new run exists. The candidate replays the inherited prefix against a
staged copy of the fork, so a document resolves its paths through the
Workspace the fork will actually have, and a guard ends the replay on
the last inherited event — before the first effect after the checkpoint
is entered, and before anything is appended. A divergent candidate
leaves no fork.

`history --forkable` reports which checkpoints a fork may select, under
four stable blocker codes that name the earliest event introducing each
and nothing a retained description held.

Version 1 gains two tables in place: the fork's lineage, and the source
run and event behind each inherited row.

Author: taras

architecture.md

@@ -854,8 +854,7 @@ the journal and the document receive only the fingerprint.
 
 The command selects the environment; the document describes the procedure.
 `xmd run` uses the caller's current environment and makes no restoration
-promise. The specified future `xmd workflow` command creates a workflow run with
-one implicit root Workspace. The same declarative components use contextual
+promise. `xmd workflow` creates a workflow run with one implicit root Workspace. The same declarative components use contextual
 capabilities in both modes; the workflow host supplies the stronger durability
 and authority boundary.
 
@@ -1079,10 +1078,29 @@ because a live operation that appended nothing would leave the next one to
 append at its position.
 
 Every committed journal event references the current logical Workspace root.
-Only committed event boundaries are checkpoints. A history fork cheaply retains
-or clones the selected root, replays the inherited prefix under a compatible
-modified definition and appends new history under a new run ID. It never rewinds
-external branches, pushes, pull requests or provider state.
+Only committed event boundaries are checkpoints. A history fork copies the
+selected root and the roots the inherited prefix names into the new run, replays
+the inherited prefix under a compatible modified definition and appends new
+history under a new run ID. It never rewinds external branches, pushes, pull
+requests or provider state.
+
+A fork writes two records for itself and inherits the rest. Its own
+`workflow_run` record is what its journal is held to, and its own root import is
+what makes the run a run of the definition the caller named — that record holds
+the document's text, so inheriting the source's would run the source's document
+whatever was asked for. Everything after them travels unchanged, keeping its
+public event ID, its filtered result, its authored position and its Workspace
+root, and carrying the source run and source event it came from. Retention moves
+with the fork: once the fork commits, deleting the source leaves its prefix and
+its selected root exactly as readable as they were.
+
+Compatibility is decided before any storage the host would recognize as the new
+run exists. The candidate replays the inherited prefix against a staged copy of
+the fork — the whole run, assembled where nothing discovers it — and the replay
+ends at the checkpoint, before the first live effect, rather than after it. A
+divergent candidate leaves no fork. After it succeeds, one transaction commits
+the run, its lineage, the inherited prefix, the copied roots, the selected
+current root and the first document execution together.
 
 ## Agent authority and generated XMD
 
@@ -1150,7 +1168,8 @@ after SQLite has restored the prior frontier.
 
 Retained roots, manifests and blobs remain indefinitely. Cloudflare garbage
 collection is not in the production closure and is never invoked. The provider
-exposes no public history selection or fork operation at this layer. Its
+exposes no public history selection at this layer; a fork's root copying is a
+lifecycle transaction above it. Its
 coordinator combines one mutation, immutable-root publication and one filtered
 journal result atomically, and the transaction-bound Files provider is what
 routes a document's `<File>` and `<Glob>` to it. `xmd workflow start` and
@@ -2283,7 +2302,7 @@ Status is measured against main.
 | `Git.Push` | publishes the selected checkout's exact current named branch and commit to the same branch on the retained Repository's canonical `origin`, reconciled through the shared Git-host state machine rather than through a Workspace transaction: no props and no component result, no force, no upstream mutation and no implicit staging or committing; the durable request and record carry the Repository's filtered identity without its checkout path, and the transport runs in a provider-owned isolated control repository reading the checkout's objects through an object-source attachment whose alternates chain and object tree are proven contained before the first remote observation, aimed at the exact private retained locator | built on the #370 stack, Deno provider only |
 | workflow lifecycle inspection and control | reads status/list/history without advancing a run, enforces the executor lock, refuses live cancellation, cancels non-live runs under that lock and deletes retained state | built on the #367 stack |
 | historical authored source | retains an authored durable operation's normalized `SourcePosition` beside its identity, and history parses it or refuses the entry | built on the #367 stack |
-| history fork | creates a new run from one compatible checkpoint and retained Workspace root | defined in `specs/workflow-workspace-spec.md`, unbuilt (#368) |
+| history fork | creates a new run from one compatible checkpoint and retained Workspace root, under a new immutable definition and normalized props | built on the #368 stack, Deno provider only |
 | read-only workflow Agent / generated XMD | lets an Agent inspect a derived view and propose constrained executable changes | defined in `specs/workflow-workspace-spec.md`, unbuilt |
 | Deno-local DOFS provider | owns one authoritative SQLite/DOFS connection per run path, captures arbitrary canonical retained roots, privately restores them, and atomically coordinates one Workspace mutation with its filtered Yield | built on the #365 stack; public document filesystem effects and the CLI lifecycle route to it on the #366 stack |
 | scoped Worker Shell | executes `just-bash` through the Workspace adapter inside a Deno Worker | containment and effect-transaction POCs complete (#351, #357); production integration unbuilt |

packages/cli/src/cli.ts

@@ -511,6 +511,14 @@ interface DocumentConfig {
    * quietly empty the process results a resumed workflow reads back.
    */
   retainProcessOutput: boolean;
+  /**
+   * Whether what this execution renders is kept from the reader.
+   *
+   * A fork's compatibility replay re-renders history that already happened in
+   * another run, and the fork's own execution renders it again a moment later.
+   * The default is that a reader sees what a document produced.
+   */
+  discardOutput?: boolean;
 }
 
 interface DocumentMode {
@@ -676,9 +684,10 @@ function* runDocument(
   // observability, shown on stderr under --verbose and dropped otherwise.
   // Interactive TTY: write each chunk as it arrives.
   // Piped: collect and write the full output at the end.
+  const discarded = config.discardOutput === true;
   const fullOutput = yield* forEach(function* (chunk: string) {
-    if (valueRoot) {
-      if (verbose) {
+    if (valueRoot || discarded) {
+      if (verbose && !discarded) {
         process.stderr.write(chunk);
       }
       return;
@@ -689,7 +698,7 @@ function* runDocument(
   }, execution.output);
 
   // When piped (not TTY), write the full output at the end.
-  if (!valueRoot && !process.stdout.isTTY) {
+  if (!valueRoot && !discarded && !process.stdout.isTTY) {
     process.stdout.write(fullOutput);
   }
 
@@ -1006,7 +1015,7 @@ interface PropsPhase {
    * positional written after `--` is not in it, and asking the parser again
    * would lose exactly the token the separator was there to protect.
    */
-  workflow?: { action?: string; target?: string; suspension?: string; answer?: string };
+  workflow?: { action?: string; target?: string; argument?: string; value?: string };
   root?: RootDocumentSource;
   bindings: Binding[];
   extraction?: Extraction;
@@ -1161,21 +1170,23 @@ function exactRoot(root: RootDocumentSource, target: string | undefined): RootDo
  * The props phase of a `workflow` invocation.
  *
  * `start` reads what the pinned definition declares, so its generated
- * `--props-*` arguments are exactly `xmd run`'s for that document. `resume`
+ * `--props-*` arguments are exactly `xmd run`'s for that document. A `fork`
+ * reads the same way, from the definition it names as its third argument: the
+ * fork is a run of that document, so its props are that document's. `resume`
  * declares nothing at all: its props are the ones the run retained, and any
  * spelling that would supply new ones is refused rather than ignored.
  */
 function* prepareWorkflowProps(
   rawArgs: string[],
   args: string[],
-  config: { action?: string; target?: string; suspension?: string; answer?: string },
+  config: { action?: string; target?: string; argument?: string; value?: string },
   inlineDocument: string | undefined,
 ): Operation<PropsPhase> {
   const workflow = {
     action: config.action,
     target: config.target,
-    suspension: config.suspension,
-    answer: config.answer,
+    argument: config.argument,
+    value: config.value,
   };
   if (inlineDocument !== undefined) {
     return {
@@ -1202,7 +1213,11 @@ function* prepareWorkflowProps(
   }
 
   const stray = findPropsFlag(args);
-  if (config.action !== "start") {
+  // Only the two actions that name a definition declare properties. A fork
+  // names its own, as its third argument: it is a run of that document, so the
+  // generated arguments are that document's rather than the source run's.
+  const definitionPath = workflowDefinitionPath(config);
+  if (definitionPath === undefined) {
     if (stray) {
       const action = config.action ?? "resume";
       return {
@@ -1217,11 +1232,11 @@ function* prepareWorkflowProps(
     return { args, bindings: [], workflow };
   }
 
-  if (config.target === undefined || config.target === "") {
+  if (definitionPath === "") {
     return { args, bindings: [], workflow };
   }
 
-  const established = yield* establishDefinition(config.target);
+  const established = yield* establishDefinition(definitionPath);
   if (!established.ok) {
     return { args, bindings: [], workflow, error: established.error.message };
   }
@@ -1249,6 +1264,28 @@ function* prepareWorkflowProps(
   }
 }
 
+/**
+ * The document one `workflow` invocation runs, when it names one.
+ *
+ * `start` names it as its only argument and `fork` as its second; every other
+ * action names a run and no definition at all. The empty string is a definition
+ * the caller has not written yet, which the props phase reports later as a
+ * missing argument rather than as an establishment failure.
+ */
+function workflowDefinitionPath(config: {
+  action?: string;
+  target?: string;
+  argument?: string;
+}): string | undefined {
+  if (config.action === "start") {
+    return config.target ?? "";
+  }
+  if (config.action === "fork") {
+    return config.argument ?? "";
+  }
+  return undefined;
+}
+
 /**
  * Whether these arguments select the `workflow` command.
  *
@@ -1269,19 +1306,20 @@ function namesWorkflow(args: string[]): boolean {
  * exists to prevent, since a document never selects a run.
  *
  * Read from the argv the props phase already stripped, so a generated property
- * value is not mistaken for an argument. `--id` is the one option that takes a
- * separated value, and `--` ends option parsing: every token after it is
+ * value is not mistaken for an argument. `--id` and `--at` are the options that
+ * take a separated value, and `--` ends option parsing: every token after it is
  * positional, including one that begins with `-`.
  */
 function extraWorkflowArgument(args: string[], action?: string): string | undefined {
   const start = args.indexOf("workflow");
   if (start === -1) {
     return undefined;
   }
-  // The action is itself the first positional. Every action but `answer` takes
-  // one more; `answer` takes three, because a delivery names the run, the wait
-  // inside it and the value in that order.
-  const allowed = action === "answer" ? 4 : 2;
+  // The action is itself the first positional. Most actions take one more;
+  // `fork` takes two, because it names the run it continues and the document it
+  // continues with; `answer` takes three, because a delivery names the run, the
+  // wait inside it and the value in that order.
+  const allowed = action === "answer" ? 4 : action === "fork" ? 3 : 2;
   let positionals = 0;
   let skip = false;
   let parsingOptions = true;
@@ -1299,7 +1337,7 @@ function extraWorkflowArgument(args: string[], action?: string): string | undefi
       continue;
     }
     if (parsingOptions && arg.startsWith("-")) {
-      skip = arg === "--id";
+      skip = arg === "--id" || arg === "--at";
       continue;
     }
     positionals += 1;
@@ -1340,14 +1378,14 @@ function separateArgs(args: string[]): SeparatedArgs {
  * separator it is positional because of where it is.
  */
 function workflowPositionals(
-  config: { action?: string; target?: string; suspension?: string; answer?: string },
+  config: { action?: string; target?: string; argument?: string; value?: string },
   tail: string[],
-): { action?: string; target?: string; suspension?: string; answer?: string } {
-  const named = [config.action, config.target, config.suspension, config.answer].filter(
-    (value) => value !== undefined,
+): { action?: string; target?: string; argument?: string; value?: string } {
+  const named = [config.action, config.target, config.argument, config.value].filter(
+    (written) => written !== undefined,
   );
-  const [action, target, suspension, answer] = [...named, ...tail];
-  return { action, target, suspension, answer };
+  const [action, target, argument, value] = [...named, ...tail];
+  return { action, target, argument, value };
 }
 
 const COMMAND_NAMES = ["run", "test", "test-agent", "workflow"];
@@ -1681,6 +1719,9 @@ function* dispatch(
               // It names no `--journal`, which is exactly why this is stated
               // here and never derived from that pathname.
               retainProcessOutput: true,
+              // A fork's compatibility replay renders history another run
+              // already produced; the fork's own execution renders it again.
+              ...(execution.discardOutput === true ? { discardOutput: true } : {}),
             },
             { testing: false, props: execution.props, installations: execution.installations },
             // The workflow authority boundary sits exactly where a host