@sunshaobei/dsh-workflow 0.0.0-stage → 2.1.2

package/vendor/dynamic-workflow/analysis/promise-ops.js

@@ -0,0 +1,123 @@
+import ts from "typescript";
+import { clearExact, cloneValue, collapse, collapseInto, emptyValue, mergeInto, } from "./domain.js";
+import { applyPessimistically, recordCall } from "./calls.js";
+/**
+ * Promise and constructor transfer rules, split out of calls.ts (max-lines): the unknown-`new`
+ * keystone with the promise-executor rule, `await` of a thenable, `Promise.reject`, and the
+ * script-class constructor application. Same `Evaluator` instance, same contract; they call back into calls.ts's shared primitives.
+ */
+/** The taint fed to invocations of function `fn`'s parameters (the promise resolve/reject/
+ * continuation pattern). Empty for a non-tracked fn or one whose params are never invoked. */
+function appliedCallbackTaint(ev, fn) {
+    const out = emptyValue();
+    const id = ev.s.fnId.get(fn);
+    if (id === undefined)
+        return out;
+    const paramCount = (ev.s.fnParamSymbols.get(id) ?? []).length;
+    for (let param = 0; param < paramCount; param += 1) {
+        const captured = ev.s.phCallActualsOf(id, param);
+        if (captured !== undefined)
+            mergeInto(out, captured);
+    }
+    return out;
+}
+/**
+ * `new UnknownThing(args)` (a non-class callee: `new Promise(exec)`, `new Set([x])`): the
+ * union of the argument collapses (exact preserved, "strings launder nothing"), PLUS the
+ * unknown-call keystone — function-valued args are pessimistically applied (their return
+ * summary joins the result) — PLUS the promise-executor rule: whatever a function arg feeds
+ * to invocations of its OWN parameters joins the result (`new Promise((resolve) =>
+ * resolve(draft))` resolves to `draft`; a `reject(x)` arg lands in the pot too, an
+ * over-approximation of the rejection path). Generic: `new X(fn)` may invoke fn and capture
+ * what fn's params receive — never special-cased by name.
+ */
+export function handleNewUnknown(ev, node, ctx) {
+    const out = emptyValue();
+    const argVals = (node.arguments ?? []).map((arg) => ev.evalExpr(arg, ctx));
+    for (const argVal of argVals)
+        collapseInto(out, argVal);
+    // The pot the constructor may feed to a callback arg's params is the sibling DATA, not the
+    // callables themselves (a function arg is the callback being invoked, not data passed to a
+    // sibling), so strip `fns`: otherwise binding a param to the executor's own fn would make
+    // `resolve(draft)` dispatch as the executor and bypass the placeholder-invocation capture.
+    const pot = clearExact(out);
+    pot.fns.clear();
+    for (const argVal of argVals) {
+        applyPessimistically(ev, argVal, pot, ctx, out, node);
+        for (const fn of argVal.fns)
+            mergeInto(out, appliedCallbackTaint(ev, fn));
+    }
+    return out;
+}
+/**
+ * `await e`: model awaiting a thenable = invoking its `then`. When the awaited value carries
+ * a tracked `then` method, the promise resolves to whatever that method feeds its continuation
+ * callback (`appliedCallbackTaint`): a custom thenable whose `then(onOk)` calls
+ * `draft.then(onOk)` resolves to `draft`. When no `then` fn is visible (a plain settled value,
+ * or a thenable collapsed past field-sensitivity), the operand's own taint already flows
+ * through unchanged — the await is a passthrough, as before.
+ *
+ * Both exits also RECORD the returned value as the settle oracle for this await. Recording only; the value returned to
+ * the evaluator is untouched, so no transfer rule changes.
+ */
+export function evalAwait(ev, node, ctx) {
+    const at = node.getStart(ev.s.scriptFile);
+    const inner = ev.evalExpr(node.expression, ctx);
+    const thenField = inner.fields.get("then");
+    if (thenField === undefined || thenField.fns.size === 0) {
+        ev.s.mergeSink(ev.s.awaitVal, at, inner);
+        return inner;
+    }
+    const out = cloneValue(inner);
+    for (const fn of thenField.fns) {
+        const id = ev.s.fnId.get(fn);
+        if (id !== undefined)
+            ev.s.markCalled(ctx.regionStack, id);
+        mergeInto(out, appliedCallbackTaint(ev, fn));
+    }
+    ev.s.mergeSink(ev.s.awaitVal, at, out);
+    return out;
+}
+/** `Promise.reject(x)` — a rejected promise. Await unwraps it as a THROW, so feed collapse(x)
+ * into the global thrown set (read by every catch binding). Returns collapse(x) as before
+ * (the unknown-call result), so nothing on the resolved path regresses. */
+export function handlePromiseReject(ev, node, ctx) {
+    const arg = node.arguments[0];
+    const val = arg === undefined ? emptyValue() : collapse(ev.evalExpr(arg, ctx));
+    ev.s.mergeThrown(val);
+    return val;
+}
+/** `Promise.reject` on the global Promise (textual match, mirroring {@link isJsonStringify}). */
+export function isPromiseReject(access) {
+    return ts.isIdentifier(access.expression) && access.expression.text === "Promise" && access.name.text === "reject";
+}
+/**
+ * Apply a script-local constructor `id` for a `new C(args)` (or a `super(args)` in a
+ * derived ctor): record the actuals as the constructor's parameter placeholders and
+ * write parameter mutations back into place actuals, exactly like an ordinary direct
+ * call. The constructor's OWN body (which writes `this.x = param`) is evaluated in the
+ * function pass, so the shared instance picks up the placeholder there; here we only
+ * seed the actuals. The instance itself is returned by the caller (NewExpression), never
+ * this call's result. A direct `new`/`super` keeps exactness (no clearing).
+ */
+export function applyConstructor(ev, id, ctx, argVals, argPlaces, site) {
+    recordCall(ev, id, ctx.regionStack, argVals, argPlaces, site === undefined ? undefined : { site, via: "callee" });
+}
+/**
+ * Apply an UNRESOLVABLE-heritage constructor (`new D()` where `class D extends mix(Base)`):
+ * the base class is produced by a mixin CALL we cannot resolve statically, so the inherited
+ * constructor is unreachable. Sound over-approximation: the ctor may store any argument in any
+ * field, so smear the collapsed (INEXACT) args into the instance's container-level taint —
+ * surfaced by every field read via smear-on-read — and pessimistically apply function-valued
+ * args (the keystone: the base ctor may invoke them). Never a drop.
+ */
+export function applyMixinConstructor(ev, ctx, instance, argVals) {
+    const pot = emptyValue();
+    for (const arg of argVals)
+        collapseInto(pot, arg);
+    const inexact = clearExact(pot);
+    if (mergeInto(instance, inexact))
+        ev.s.changed = true;
+    for (const arg of argVals)
+        applyPessimistically(ev, arg, inexact, ctx, instance);
+}

package/vendor/dynamic-workflow/analysis/relays.d.ts

@@ -0,0 +1,12 @@
+import ts from "typescript";
+import { type AbstractValue } from "./domain.js";
+import type { EvalContext, Evaluator } from "./taint.js";
+/**
+ * Facade sink and relay transfers: `Agent.ask`, `files.glob`/`read` (world reads), and
+ * `Promise.all` join relays. Split out of calls.ts (pure move, no behavior change) to keep
+ * that file under the line cap; `evalCall` dispatches here via the site lookups.
+ */
+export declare function handleAsk(ev: Evaluator, node: ts.CallExpression, askId: string, ctx: EvalContext): AbstractValue;
+export declare function handleWorldRead(ev: Evaluator, id: string, args: readonly ts.Expression[], ctx: EvalContext): AbstractValue;
+export declare function handleJoin(ev: Evaluator, node: ts.CallExpression, id: string, arg: ts.Expression | undefined, ctx: EvalContext): AbstractValue;
+//# sourceMappingURL=relays.d.ts.map

package/vendor/dynamic-workflow/analysis/relays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relays.d.ts","sourceRoot":"","sources":["../../src/analysis/relays.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAqD,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;GAIG;AAEH,wBAAgB,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC,cAAc,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,aAAa,CAchH;AAED,wBAAgB,eAAe,CAC7B,EAAE,EAAE,SAAS,EACb,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,SAAS,EAAE,CAAC,UAAU,EAAE,EAC9B,GAAG,EAAE,WAAW,GACf,aAAa,CAMf;AAED,wBAAgB,UAAU,CACxB,EAAE,EAAE,SAAS,EACb,IAAI,EAAE,EAAE,CAAC,cAAc,EACvB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,EAAE,CAAC,UAAU,GAAG,SAAS,EAC9B,GAAG,EAAE,WAAW,GACf,aAAa,CAyCf"}

package/vendor/dynamic-workflow/analysis/relays.js

@@ -0,0 +1,78 @@
+import ts from "typescript";
+import { addOcc, collapse, liveField, mergeInto, singleOcc } from "./domain.js";
+/**
+ * Facade sink and relay transfers: `Agent.ask`, `files.glob`/`read` (world reads), and
+ * `Promise.all` join relays. Split out of calls.ts (pure move, no behavior change) to keep
+ * that file under the line cap; `evalCall` dispatches here via the site lookups.
+ */
+export function handleAsk(ev, node, askId, ctx) {
+    ev.s.markFacade(ctx.regionStack);
+    const site = ev.s.askSites.get(askId);
+    if (site !== undefined) {
+        ev.s.mergeSink(ev.s.askRecv, askId, collapse(ev.evalExpr(site.receiver, ctx)));
+        if (site.instructions !== undefined) {
+            ev.s.mergeSink(ev.s.askInstr, askId, collapse(ev.evalExpr(site.instructions, ctx)));
+        }
+    }
+    // Evaluate any extra arguments for their side effects (heap writes etc.).
+    node.arguments.forEach((arg, index) => {
+        if (index !== 0)
+            ev.evalExpr(arg, ctx);
+    });
+    return singleOcc(askId, true);
+}
+export function handleWorldRead(ev, id, args, ctx) {
+    ev.s.markFacade(ctx.regionStack);
+    // Every positional argument is a sink: ops differ in arity (`files.grep(pattern, glob?)`,
+    // `git.diff(base?, path?)`), and an artifact reaching any of them is a data dependency.
+    for (const arg of args)
+        ev.s.mergeSink(ev.s.worldRead, id, collapse(ev.evalExpr(arg, ctx)));
+    return singleOcc(id, true);
+}
+export function handleJoin(ev, node, id, arg, ctx) {
+    ev.s.markFacade(ctx.regionStack);
+    // The join result is the PERSISTENT node of this call site (state.ts joinResultOf), NOT a
+    // fresh value per pass: it is a place other values may-alias, and the canonical-heap
+    // invariant requires every alias target to have pass-stable identity. Each merge below is
+    // therefore weak and reports its growth into `ev.s.changed` — a pass in which only this
+    // node grew must not terminate the fixpoint, or a consumer evaluated earlier in the pass
+    // (a function body, a later re-read) would never observe the growth.
+    const result = ev.s.joinResultOf(node);
+    if (arg !== undefined && ts.isArrayLiteralExpression(arg) && !arg.elements.some(ts.isSpreadElement)) {
+        // Static array literal: element positions become ports.
+        arg.elements.forEach((el, port) => {
+            const elemValue = ev.evalExpr(el, ctx);
+            ev.s.mergeJoinIn(id, port, collapse(elemValue));
+            const field = liveField(result, String(port));
+            if (mergeInto(field, elemValue))
+                ev.s.changed = true;
+            if (addOcc(field, { exact: true, port, site: id }))
+                ev.s.changed = true;
+            // A place element aliases its slot in the resolved tuple: `Promise.all([secret, box])`
+            // resolves the non-promise `box` to box ITSELF, so a write through `res[k]` / a
+            // destructured element reaches the original (weak, inexact via mayAlias). The field
+            // KEEPS the join port occ (added above), so no relay edge is lost.
+            const elemPlace = ev.resolvePlace(el);
+            if (elemPlace !== undefined) {
+                const targets = (field.mayAlias ??= new Set());
+                if (!targets.has(elemPlace)) {
+                    targets.add(elemPlace);
+                    ev.s.changed = true;
+                }
+            }
+        });
+        if (addOcc(result, { exact: true, site: id }))
+            ev.s.changed = true;
+        return result;
+    }
+    // Non-literal iterable: portless in-taint; the result is an additive relay.
+    if (arg !== undefined) {
+        const argCollapsed = collapse(ev.evalExpr(arg, ctx));
+        ev.s.mergeJoinIn(id, -1, argCollapsed);
+        if (mergeInto(result, argCollapsed))
+            ev.s.changed = true;
+    }
+    if (addOcc(result, { exact: true, site: id }))
+        ev.s.changed = true;
+    return result;
+}

package/vendor/dynamic-workflow/analysis/serialize.d.ts

@@ -0,0 +1,125 @@
+import type { ActorGraph } from "./actor-graph.js";
+import type { CausalityGraph, Lane } from "./causality-graph.js";
+import type { ControlFlowGraph } from "./flow-graph.js";
+import type { HandoffGraph } from "./handoff-graph.js";
+import type { SiteGraph } from "./types.js";
+/**
+ * Canonical, deterministic text form of a site graph — the snapshot and debugging
+ * surface. Grammar:
+ *
+ *   node source
+ *   node ask#1 "scanner" @3:24 actors=actor#1 type="Flaky"
+ *   node ask#2 "judge" @8:20 within=fan-out#1
+ *   node sink
+ *   actor actor#1 "planner" @5:17
+ *   actor actor#2 "judge" @8:14 within=fan-out#1
+ *   edge ask#1 -> ask#2 data exact type="Flaky"
+ *   edge join#1 -> sink data inexact port=2 type="Review"
+ *
+ * Nodes come first (virtual `source` first, `sink` last, sites between in source
+ * order); then actors in source order; then edges. `source`/`sink` carry no label
+ * or location. `ask` nodes carry a trailing `actors=...` lane membership when
+ * non-empty; any node or actor lexically inside a promoted fan-out carries a
+ * trailing `within=fan-out#N` (after `actors=` when both are present); a producer
+ * node/edge carries a trailing `type="<artifactType>"` last, when known (the type
+ * string is quoted with embedded `"` escaped as `\"`, since a string-literal-union
+ * artifact type can contain quotes, e.g. `ask<"yes" | "no">`). Edges are sorted by
+ * (from position, to position, kind, port).
+ */
+export declare function serializeGraph(graph: SiteGraph): string;
+/**
+ * Canonical text form of the derived {@link ActorGraph} (its own snapshot surface,
+ * a sibling of {@link serializeGraph}). Grammar:
+ *
+ *   actor-node main
+ *   actor-node workspace
+ *   actor-node actor#1 "planner" @17:17
+ *   actor-node actor#2 "judge" @29:32 family=fan-out#1
+ *   actor-edge main -> actor#1 exact count=1
+ *   actor-edge actor#1 -> actor#2 inexact count=2 types="Plan","Review"
+ *
+ * Nodes come first in node order (already `main`, then `workspace` when present,
+ * then actors in site order); edges follow, sorted by (from position, to position).
+ * `main`/`workspace` carry no name or location; actor nodes carry a `"name"` when
+ * known, always a location, and a trailing `family=fan-out#N` when they are a lane
+ * family (their site sits inside a promoted fan-out). An actor edge carries a trailing
+ * `types="A","B"` (each type individually quoted, embedded `"` escaped as `\"` — type
+ * strings can contain quotes, e.g. `ask<"yes" | "no">`) when it carries message types.
+ */
+export declare function serializeActorGraph(graph: ActorGraph): string;
+/**
+ * Canonical text form of the {@link CausalityGraph} — its snapshot and debugging
+ * surface, third sibling of {@link serializeGraph} / {@link serializeActorGraph}.
+ * Grammar:
+ *
+ *   phase unphased
+ *   phase phase#1 "preflight" @3:1
+ *   lane workspace
+ *   lane actor#2 "planner" @17:17
+ *   lane actor#4 "judge" @29:32 families=fanout#1
+ *   lane actor#1 name-head="研究员" @53:5 families=fanout#1
+ *   region seq#1 seq
+ *   region loop#1 loop parent=seq#1 @21:1 bound=5
+ *   step ask#1 ask "scanner" @14:41 lane=actor#1 region=seq#1 always
+ *   step ask#4 ask "judge" @29:47 lane=actor#4 region=fanout#1 maybe stack
+ *   step ask#2~actor#1 ask "move" @12:40 lane=actor#1 lanes=actor#1,actor#2 source=ask#2 \
+ *     phase=phase#2 region=loop#1 maybe serial
+ *   edge ask#1 -> ask#2 seq always
+ *   edge ask#3 -> ask#2 carry always
+ *   phase-edge phase#1 -> phase#2 seq always
+ *   sink ask#2,ask#4
+ *
+ * Sections are fixed: phases (when the script declares any marker at all — see below),
+ * lanes (workspace first, then actors in creation order, `unknown`
+ * last), regions in creation order, steps in source order, edges in the graph's
+ * canonical order, the phase quotient's edges, then the sink line when the script returns
+ * an artifact. `lanes=`
+ * appears on a step whose receiver is a may-set and `source=` only on a may-set COPY (so
+ * a step that did not expand serializes exactly as it did pre-expansion); `exact`/`inexact`
+ * only on `data` edges, where the bit means something.
+ *
+ * The phase vocabulary — `phase` lines, the step's `phase=` field, `phase-edge` lines —
+ * appears only when the script declares at least one `phase("…")` marker, and then all
+ * three appear. A script with no markers serializes byte-for-byte as it did before phase
+ * annotations existed; that is the regression nail the whole fixture corpus stands on.
+ *
+ * `name-head=`/`name-tail=` (lane) and `label-head=`/`label-tail=` (step) carry a
+ * {@link NamePattern} — the static shape of a name the script interpolates. They sit in
+ * the same slot as the quoted name they stand in for, and they carry the affixes as
+ * **data**: the ellipsis that turns them into `研究员…` is a render-time decision, not
+ * part of this form.
+ */
+export declare function serializeCausalityGraph(graph: CausalityGraph): string;
+/**
+ * Canonical text form of the control-flow graph,
+ * fifth sibling of the serializers above:
+ *
+ *   phase phase#1 "preflight"
+ *   phase phase#2 "review" alongside=phase#1
+ *   phase hole#21b40fca "决定分组"
+ *   hole hole#cd7e8315 "评判" type="Verdict" phase=phase#2 tail
+ *   node ask#1@1 issue site=ask#1 phase=phase#2
+ *   node phase#6@1 mark phase=phase#6 alongside=phase#1,phase#2
+ *   node ask#9@1 issue site=ask#9 phase=unphased detached
+ *   edge entry -> world-read#2@1 next
+ *   edge world-read#4@1 -> ask#1@1 loop via=continue
+ *   edge ask#3@1 -> abort throw
+ *   phase-edge phase#3 -> phase#2 loop via=continue
+ *
+ * Nodes in leaf-stream order, edges in the graph's canonical order (`entry` first, the
+ * terminals last). `phase` and `phase-edge` lines appear only when the script declares a
+ * marker — the same all-or-nothing contract as the causality serializer's phase vocabulary.
+ * `alongside` (a mark's, and its phase's union) names the phases whose strands were still
+ * running when the marker was entered; it is a node fact, never an edge. `fill=` on a phase
+ * names the filled hole whose body wrote it; a `hole` line is an OPEN hole with the phase it
+ * stands in and `tail` when it is the script's open end (docs/analysis.md「Sites」).
+ */
+export declare function serializeControlFlow(flow: ControlFlowGraph): string;
+/**
+ * Canonical text form of the hand-off graph,
+ * snapshotted as `<fixture>.handoff.txt`. Participants in the analyzer's order (which IS
+ * the stack order), grouped under their phase; the lane's literal name is echoed for
+ * readability only — `lanes` carries it in the payload.
+ */
+export declare function serializeHandoffGraph(graph: HandoffGraph, lanes: readonly Lane[]): string;
+//# sourceMappingURL=serialize.d.ts.map

package/vendor/dynamic-workflow/analysis/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/analysis/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,UAAU,EAAa,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EACV,cAAc,EACd,IAAI,EAML,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,gBAAgB,EAAY,MAAM,iBAAiB,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAuB,SAAS,EAAY,MAAM,YAAY,CAAC;AAO3E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAevD;AAmCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAM7D;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAWrE;AA+DD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CA4BnE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,MAAM,CAwBzF"}

package/vendor/dynamic-workflow/analysis/serialize.js

@@ -0,0 +1,321 @@
+/** Quote a type string for a `type=`/`types=` field: embedded `"` escaped as `\"`. */
+function quoteType(type) {
+    return `"${type.replace(/"/g, '\\"')}"`;
+}
+/**
+ * Canonical, deterministic text form of a site graph — the snapshot and debugging
+ * surface. Grammar:
+ *
+ *   node source
+ *   node ask#1 "scanner" @3:24 actors=actor#1 type="Flaky"
+ *   node ask#2 "judge" @8:20 within=fan-out#1
+ *   node sink
+ *   actor actor#1 "planner" @5:17
+ *   actor actor#2 "judge" @8:14 within=fan-out#1
+ *   edge ask#1 -> ask#2 data exact type="Flaky"
+ *   edge join#1 -> sink data inexact port=2 type="Review"
+ *
+ * Nodes come first (virtual `source` first, `sink` last, sites between in source
+ * order); then actors in source order; then edges. `source`/`sink` carry no label
+ * or location. `ask` nodes carry a trailing `actors=...` lane membership when
+ * non-empty; any node or actor lexically inside a promoted fan-out carries a
+ * trailing `within=fan-out#N` (after `actors=` when both are present); a producer
+ * node/edge carries a trailing `type="<artifactType>"` last, when known (the type
+ * string is quoted with embedded `"` escaped as `\"`, since a string-literal-union
+ * artifact type can contain quotes, e.g. `ask<"yes" | "no">`). Edges are sorted by
+ * (from position, to position, kind, port).
+ */
+export function serializeGraph(graph) {
+    const source = graph.nodes.filter((node) => node.kind === "source");
+    const sink = graph.nodes.filter((node) => node.kind === "sink");
+    const middle = graph.nodes.filter((node) => node.kind !== "source" && node.kind !== "sink");
+    const ordered = [...source, ...middle, ...sink];
+    const position = new Map(ordered.map((node, index) => [node.id, index]));
+    const edges = [...graph.edges].sort((a, b) => compareEdges(a, b, position));
+    const lines = [
+        ...ordered.map(renderNode),
+        ...graph.actors.map(renderActor),
+        ...edges.map(renderEdge),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+function renderNode(node) {
+    if (node.loc === undefined)
+        return `node ${node.id}`;
+    let line = `node ${node.id} "${node.label}" @${node.loc.line}:${node.loc.column}`;
+    if (node.actors !== undefined && node.actors.length > 0)
+        line += ` actors=${node.actors.join(",")}`;
+    if (node.within !== undefined)
+        line += ` within=${node.within}`;
+    if (node.artifactType !== undefined)
+        line += ` type=${quoteType(node.artifactType)}`;
+    return line;
+}
+function renderActor(actor) {
+    const name = actor.name === undefined ? "" : ` "${actor.name}"`;
+    let line = `actor ${actor.id}${name} @${actor.loc.line}:${actor.loc.column}`;
+    if (actor.within !== undefined)
+        line += ` within=${actor.within}`;
+    return line;
+}
+function renderEdge(edge) {
+    const exact = edge.exact ? "exact" : "inexact";
+    const port = edge.port === undefined ? "" : ` port=${edge.port}`;
+    const type = edge.type === undefined ? "" : ` type=${quoteType(edge.type)}`;
+    return `edge ${edge.from} -> ${edge.to} ${edge.kind} ${exact}${port}${type}`;
+}
+function compareEdges(a, b, position) {
+    const rank = (id) => position.get(id) ?? Number.MAX_SAFE_INTEGER;
+    return (rank(a.from) - rank(b.from) ||
+        rank(a.to) - rank(b.to) ||
+        a.kind.localeCompare(b.kind) ||
+        (a.port ?? -1) - (b.port ?? -1));
+}
+/**
+ * Canonical text form of the derived {@link ActorGraph} (its own snapshot surface,
+ * a sibling of {@link serializeGraph}). Grammar:
+ *
+ *   actor-node main
+ *   actor-node workspace
+ *   actor-node actor#1 "planner" @17:17
+ *   actor-node actor#2 "judge" @29:32 family=fan-out#1
+ *   actor-edge main -> actor#1 exact count=1
+ *   actor-edge actor#1 -> actor#2 inexact count=2 types="Plan","Review"
+ *
+ * Nodes come first in node order (already `main`, then `workspace` when present,
+ * then actors in site order); edges follow, sorted by (from position, to position).
+ * `main`/`workspace` carry no name or location; actor nodes carry a `"name"` when
+ * known, always a location, and a trailing `family=fan-out#N` when they are a lane
+ * family (their site sits inside a promoted fan-out). An actor edge carries a trailing
+ * `types="A","B"` (each type individually quoted, embedded `"` escaped as `\"` — type
+ * strings can contain quotes, e.g. `ask<"yes" | "no">`) when it carries message types.
+ */
+export function serializeActorGraph(graph) {
+    const position = new Map(graph.nodes.map((node, index) => [node.id, index]));
+    const rank = (id) => position.get(id) ?? Number.MAX_SAFE_INTEGER;
+    const edges = [...graph.edges].sort((a, b) => rank(a.from) - rank(b.from) || rank(a.to) - rank(b.to));
+    const lines = [...graph.nodes.map(renderActorNode), ...edges.map(renderActorEdge)];
+    return `${lines.join("\n")}\n`;
+}
+function renderActorNode(node) {
+    let line = `actor-node ${node.id}`;
+    if (node.name !== undefined)
+        line += ` "${node.name}"`;
+    if (node.loc !== undefined)
+        line += ` @${node.loc.line}:${node.loc.column}`;
+    if (node.family !== undefined)
+        line += ` family=${node.family}`;
+    return line;
+}
+function renderActorEdge(edge) {
+    let line = `actor-edge ${edge.from} -> ${edge.to} ${edge.exact ? "exact" : "inexact"} count=${edge.count}`;
+    if (edge.types !== undefined && edge.types.length > 0) {
+        line += ` types=${edge.types.map(quoteType).join(",")}`;
+    }
+    return line;
+}
+/**
+ * Canonical text form of the {@link CausalityGraph} — its snapshot and debugging
+ * surface, third sibling of {@link serializeGraph} / {@link serializeActorGraph}.
+ * Grammar:
+ *
+ *   phase unphased
+ *   phase phase#1 "preflight" @3:1
+ *   lane workspace
+ *   lane actor#2 "planner" @17:17
+ *   lane actor#4 "judge" @29:32 families=fanout#1
+ *   lane actor#1 name-head="研究员" @53:5 families=fanout#1
+ *   region seq#1 seq
+ *   region loop#1 loop parent=seq#1 @21:1 bound=5
+ *   step ask#1 ask "scanner" @14:41 lane=actor#1 region=seq#1 always
+ *   step ask#4 ask "judge" @29:47 lane=actor#4 region=fanout#1 maybe stack
+ *   step ask#2~actor#1 ask "move" @12:40 lane=actor#1 lanes=actor#1,actor#2 source=ask#2 \
+ *     phase=phase#2 region=loop#1 maybe serial
+ *   edge ask#1 -> ask#2 seq always
+ *   edge ask#3 -> ask#2 carry always
+ *   phase-edge phase#1 -> phase#2 seq always
+ *   sink ask#2,ask#4
+ *
+ * Sections are fixed: phases (when the script declares any marker at all — see below),
+ * lanes (workspace first, then actors in creation order, `unknown`
+ * last), regions in creation order, steps in source order, edges in the graph's
+ * canonical order, the phase quotient's edges, then the sink line when the script returns
+ * an artifact. `lanes=`
+ * appears on a step whose receiver is a may-set and `source=` only on a may-set COPY (so
+ * a step that did not expand serializes exactly as it did pre-expansion); `exact`/`inexact`
+ * only on `data` edges, where the bit means something.
+ *
+ * The phase vocabulary — `phase` lines, the step's `phase=` field, `phase-edge` lines —
+ * appears only when the script declares at least one `phase("…")` marker, and then all
+ * three appear. A script with no markers serializes byte-for-byte as it did before phase
+ * annotations existed; that is the regression nail the whole fixture corpus stands on.
+ *
+ * `name-head=`/`name-tail=` (lane) and `label-head=`/`label-tail=` (step) carry a
+ * {@link NamePattern} — the static shape of a name the script interpolates. They sit in
+ * the same slot as the quoted name they stand in for, and they carry the affixes as
+ * **data**: the ellipsis that turns them into `研究员…` is a render-time decision, not
+ * part of this form.
+ */
+export function serializeCausalityGraph(graph) {
+    const lines = [
+        ...(graph.phases ?? []).map(renderPhase),
+        ...graph.lanes.map(renderLane),
+        ...graph.regions.map(renderRegion),
+        ...graph.steps.map(renderStep),
+        ...graph.edges.map(renderOrderEdge),
+        ...(graph.phaseEdges ?? []).map(renderPhaseEdge),
+        ...(graph.sink === undefined ? [] : [`sink ${graph.sink.fedBy.join(",")}`]),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+function renderPhase(phase) {
+    let line = `phase ${phase.id}`;
+    if (phase.name !== undefined)
+        line += ` "${phase.name}"`;
+    if (phase.loc !== undefined)
+        line += ` @${phase.loc.line}:${phase.loc.column}`;
+    if (phase.fill !== undefined)
+        line += ` fill=${phase.fill}`;
+    return line;
+}
+function renderPhaseEdge(edge) {
+    return `phase-edge ${edge.from} -> ${edge.to} ${edge.kind} ${edge.certainty}`;
+}
+function renderLane(lane) {
+    let line = `lane ${lane.id}`;
+    if (lane.name !== undefined)
+        line += ` "${lane.name}"`;
+    line += renderNamePattern("name", lane.namePattern);
+    if (lane.loc !== undefined)
+        line += ` @${lane.loc.line}:${lane.loc.column}`;
+    if (lane.families !== undefined && lane.families.length > 0) {
+        line += ` families=${lane.families.join(",")}`;
+    }
+    return line;
+}
+/** `name-head="研究员" name-tail="-worker"` — affixes as data, never the rendered glyph. */
+function renderNamePattern(field, pattern) {
+    if (pattern === undefined)
+        return "";
+    let out = "";
+    if (pattern.head !== undefined)
+        out += ` ${field}-head=${quoteType(pattern.head)}`;
+    if (pattern.tail !== undefined)
+        out += ` ${field}-tail=${quoteType(pattern.tail)}`;
+    return out;
+}
+function renderRegion(region) {
+    let line = `region ${region.id} ${region.kind}`;
+    if (region.parent !== undefined)
+        line += ` parent=${region.parent}`;
+    if (region.loc !== undefined)
+        line += ` @${region.loc.line}:${region.loc.column}`;
+    if (region.bound !== undefined)
+        line += ` bound=${region.bound}`;
+    if (region.label !== undefined)
+        line += ` label=${quoteType(region.label)}`;
+    return line;
+}
+function renderStep(step) {
+    let line = `step ${step.id} ${step.kind} "${step.label}"`;
+    line += renderNamePattern("label", step.labelPattern);
+    line += ` @${step.loc.line}:${step.loc.column}`;
+    line += ` lane=${step.lane}`;
+    if (step.lanes !== undefined)
+        line += ` lanes=${step.lanes.join(",")}`;
+    if (step.source !== undefined)
+        line += ` source=${step.source}`;
+    if (step.phase !== undefined)
+        line += ` phase=${step.phase}`;
+    line += ` region=${step.region} ${step.certainty}`;
+    if (step.repeat !== undefined)
+        line += ` ${step.repeat}`;
+    if (step.fill !== undefined)
+        line += ` fill=${step.fill}`;
+    return line;
+}
+function renderOrderEdge(edge) {
+    let line = `edge ${edge.from} -> ${edge.to} ${edge.kind} ${edge.certainty}`;
+    if (edge.exact !== undefined)
+        line += edge.exact ? " exact" : " inexact";
+    return line;
+}
+/**
+ * Canonical text form of the control-flow graph,
+ * fifth sibling of the serializers above:
+ *
+ *   phase phase#1 "preflight"
+ *   phase phase#2 "review" alongside=phase#1
+ *   phase hole#21b40fca "决定分组"
+ *   hole hole#cd7e8315 "评判" type="Verdict" phase=phase#2 tail
+ *   node ask#1@1 issue site=ask#1 phase=phase#2
+ *   node phase#6@1 mark phase=phase#6 alongside=phase#1,phase#2
+ *   node ask#9@1 issue site=ask#9 phase=unphased detached
+ *   edge entry -> world-read#2@1 next
+ *   edge world-read#4@1 -> ask#1@1 loop via=continue
+ *   edge ask#3@1 -> abort throw
+ *   phase-edge phase#3 -> phase#2 loop via=continue
+ *
+ * Nodes in leaf-stream order, edges in the graph's canonical order (`entry` first, the
+ * terminals last). `phase` and `phase-edge` lines appear only when the script declares a
+ * marker — the same all-or-nothing contract as the causality serializer's phase vocabulary.
+ * `alongside` (a mark's, and its phase's union) names the phases whose strands were still
+ * running when the marker was entered; it is a node fact, never an edge. `fill=` on a phase
+ * names the filled hole whose body wrote it; a `hole` line is an OPEN hole with the phase it
+ * stands in and `tail` when it is the script's open end (docs/analysis.md「Sites」).
+ */
+export function serializeControlFlow(flow) {
+    const edgeLine = (head, edge) => `${head} ${edge.from} -> ${edge.to} ${edge.kind}${edge.via === undefined ? "" : ` via=${edge.via}`}`;
+    const lines = [
+        ...(flow.phases ?? []).map((phase) => `phase ${phase.id}${phase.name === undefined ? "" : ` ${quoteType(phase.name)}`}` +
+            (phase.alongside === undefined ? "" : ` alongside=${phase.alongside.join(",")}`) +
+            (phase.fill === undefined ? "" : ` fill=${phase.fill}`)),
+        ...(flow.holes ?? []).map((hole) => `hole ${hole.siteId} ${quoteType(hole.name)} type=${quoteType(hole.type)}` +
+            (hole.phase === undefined ? "" : ` phase=${hole.phase}`) +
+            (hole.tail ? " tail" : "")),
+        ...flow.nodes.map((node) => `node ${node.id} ${node.kind}` +
+            (node.site === undefined ? "" : ` site=${node.site}`) +
+            ` phase=${node.phase}` +
+            (node.alongside === undefined ? "" : ` alongside=${node.alongside.join(",")}`) +
+            (node.detached ? " detached" : "")),
+        ...flow.edges.map((edge) => edgeLine("edge", edge)),
+        ...(flow.phaseEdges ?? []).map((edge) => edgeLine("phase-edge", edge)),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Canonical text form of the hand-off graph,
+ * snapshotted as `<fixture>.handoff.txt`. Participants in the analyzer's order (which IS
+ * the stack order), grouped under their phase; the lane's literal name is echoed for
+ * readability only — `lanes` carries it in the payload.
+ */
+export function serializeHandoffGraph(graph, lanes) {
+    const nameOf = new Map(lanes.map((lane) => [lane.id, lane.name]));
+    const lines = [];
+    let phase;
+    for (const participant of graph.participants) {
+        if (participant.phase !== phase) {
+            phase = participant.phase;
+            lines.push(`phase ${phase}`);
+        }
+        let line = `participant ${participant.id}`;
+        const name = nameOf.get(participant.lane);
+        if (name !== undefined)
+            line += ` ${quoteType(name)}`;
+        if (participant.member !== undefined)
+            line += ` member=${participant.member.index}/${participant.member.of}`;
+        if (participant.many)
+            line += " many";
+        line += ` steps=${participant.steps.join(",")}`;
+        lines.push(line);
+    }
+    for (const edge of graph.handoffs) {
+        let line = `handoff ${edge.from} -> ${edge.to}`;
+        if (edge.back)
+            line += " back";
+        if (edge.types !== undefined)
+            line += ` types=${quoteType(edge.types.join(","))}`;
+        lines.push(line);
+    }
+    return `${lines.join("\n")}\n`;
+}