skynet-graph 1.2.0

package/lib/durable/interpreter.js

@@ -0,0 +1,242 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * interpreter — LAYER B of the durable executor: the per-record TOKEN-FLOW interpreter. It walks case records
+ * through a compiled workflow-net (`xlate.js`) VIA the `CheckpointStore` (`checkpoint-store.js`), so position is
+ * durable + crash-resumable and each step is content-memoized. This is the skynet-NATIVE half the convergence
+ * study (§5 Layer B) keeps out of the commodity plumbing: typed routing (from `selectCluster`'s gates) and
+ * per-case determinism live here.
+ *
+ *   const store = createCheckpointStore({ file });
+ *   const net   = compileMethod(spec);
+ *   store.ensureRun(runId, net); store.inject(runId, records);
+ *   const m = runFlow(store, runId, net, { runTask });   // drains to a fixpoint; resume by calling it again
+ *
+ * Per-case determinism: each token carries its OWN payload (its world); cross-record interleaving is
+ * non-deterministic THROUGHPUT, not belief (the §12.3 belief↔durable line). A transition fires by kind:
+ *  - select : evaluate the typed gates (the SAME `when` exprs as `selectCluster`, via the safe `expr.js`
+ *             evaluator) against the record's facts → move to the matching branch; no match → the fallback.
+ *  - task   : a provider MICRO-TASK. Content-addressed memo (C5): key = FactsDigest(canonical step input); a
+ *             HIT replays at 0 calls (this is what makes crash-resume cheap AND amortizes a recurrent stream).
+ *             A null `keyOf` BYPASSES the memo (fail-open, like cache.js); a null task = a no-op passthrough.
+ *  - map    : Brick-1 fan-out — one child token per element of the `over` collection, each with its own
+ *             `elemKey` (fresh per-child payload, #30) + `_i` (element index) + `_n` (the cardinality).
+ *  - join   : the fan-IN (the JTMS-at-merge point). Layer A's `joinArrive` parks the held child and, when all
+ *             `_n` siblings of the fan-out group have arrived, spawns ONE collector at the fold place carrying
+ *             their payloads. A BOUNDED PROJECTION (N retained-for-audit → 1), not a destructive ref-swap.
+ *  - fold   : reduce the collected siblings to one value. A declared MONOID (`fold.js`, pure + order-independent
+ *             — non-deterministic THROUGHPUT, deterministic BELIEF) OR a micro-TASK (small-LLM reconciliation,
+ *             content-memoized like any task). map.reduce = "map ∘ reduce" end to end.
+ *
+ * Termination = fuel (`maxSteps`): a step-indexed cutoff (a cyclic/divergent net stops; §4B), not a claim that
+ * the net is sound (defeasance makes static workflow-soundness undecidable — we run to a fuel-bounded fixpoint).
+ */
+const { compileExpression } = require('../graph/expr.js');
+const { indexByFrom } = require('./xlate.js');
+const { stableStringify } = require('../providers/cache.js');
+const { foldSiblings } = require('./fold.js');
+
+// resolve a `$ref` token against a flat/dotted record payload (the case's typed facts). selectCluster gates are
+// flat typed facts; dotted access is supported for convenience. (Cross-object `:` walks are an engine concern.)
+function resolveFact( payload, ref ) {
+	if ( payload == null ) return undefined;
+	if ( ref.indexOf('.') < 0 ) return payload[ref];
+	return ref.split('.').reduce(( o, k ) => (o == null ? undefined : o[k]), payload);
+}
+
+// default content-memo key: the task + the FULL canonical payload, via a RECURSIVE key-sorted stringify (NOT
+// `canonicalize.digest`, whose sorted-keys arg is a JSON.stringify ALLOWLIST applied at every nesting level → it
+// silently STRIPS nested payload keys → every element collapses to one key → a false hit; finding #35, the F4
+// risk in the default). This default is SOUND but conservative (incidental fields re-key); a host projects to the
+// TRACKED facts via `keyOf` for amortization (the K1 discipline — see `examples/poc/durable-flow.js`).
+function defaultKeyOf( tr, token ) { return 'task:' + tr.task + '|' + stableStringify(token.payload || {}); }
+
+/**
+ * Drain a run to a fixpoint over the CheckpointStore. Idempotent + resumable: call it again after a crash (the
+ * caller should `store.rollbackInflight(runId)` first to recover any in-flight token).
+ *
+ * @param store   a CheckpointStore
+ * @param runId
+ * @param net     a compiled net (`compileMethod`)
+ * @param opts.runTask  (task, token) => ({ payload?, created? }) | Promise<...>   — REQUIRED: run a micro-task
+ *                       (provider/LLM). May be ASYNC (a real LLM call). Returns a payload PATCH (merged forward)
+ *                       + optional createdRefs. Pure-compute or effecting.
+ * @param opts.keyOf    (transition, token) => string|null        — memo key (default: task+canonical payload).
+ * @param opts.lease    ms a claimed token is held (default 30000)
+ * @param opts.batch    tokens leased per claim (default 32)
+ * @param opts.maxSteps fuel — transition firings before a divergent cutoff (default 100000)
+ * @param opts.foldKeyOf (transition, sortedSiblings) => string|null  — memo key for a micro-TASK fold.
+ * @returns { steps, taskCalls, memoHits, bypass, fanOut, routed, joins, joinParked, folds, done, failed } — counters.
+ */
+async function runFlow( store, runId, net, opts ) {
+	opts = opts || {};
+	const runTask = opts.runTask;
+	if ( typeof runTask !== 'function' ) throw new Error('runFlow: opts.runTask (task, token) => {payload?,created?} is required');
+	const keyOf = opts.keyOf || defaultKeyOf;
+	// the fold-task memo key: keyed on the COLLECTED sibling inputs (a superset of what the fold reads → sound).
+	// Recursive stringify (NOT digest — same #35 nested-strip trap as defaultKeyOf).
+	const foldKeyOf = opts.foldKeyOf || (( tr, sibs ) => 'fold:' + tr.reduce.task + '|' + stableStringify(sibs));
+	// the per-step C-contract guard (assert-before-commit). Lazy-required so an executor-only run without any
+	// transition `contract` never loads the authoring layer; a host may inject its own `assertStep`.
+	const assertStep = opts.assertStep || (( contract, facts, touched, o ) => require('../authoring/contract.js').assertPost(contract, facts, touched, o));
+	// fail a token; if it is a REDUCING-map child (stamped `_join`), FAIL-FAST its whole group so the join can't
+	// hang waiting for a sibling that will never arrive (C-fail). A plain token just dead-letters.
+	// a REDUCING-map child (stamped `_join`) that fails: the GROUP POLICY (`_onFail`, stamped at fan-out) decides —
+	// 'survivors' DROPS just this shard (joinFail → the join still folds the rest + a `_partial` marker), 'failfast'
+	// (default) fails the WHOLE group so the join can't hang waiting on a sibling that will never arrive. A plain
+	// token just dead-letters. (`byFrom` is captured by closure — resolved at call-time, after it's initialized.)
+	const failToken = ( tk, reason ) => {
+		const p = tk.payload || {};
+		if ( !p._join ) return store.fail(tk, reason);
+		if ( p._onFail === 'survivors' ) {
+			const joinTr = byFrom[p._join];
+			return store.joinFail(tk, p._join, { expected: p._n, foldPlace: joinTr && joinTr.foldPlace, failPlace: net.fail, reason });
+		}
+		return store.failGroup(tk, p._join, net.fail, reason);
+	};
+	// the C-fail LADDER at a task-failure site (a task throw OR a contract blame), BEFORE the terminal fail:
+	//   retry (bounded `tr.retry`, for transient/non-deterministic tasks — re-ready the SAME place; the failure was
+	//          never memoized so it re-runs fresh) → escalate (once, `tr.escalate` → a bigger micro-task place that
+	//          rejoins the flow on success) → fall through to failToken (group policy). Counters: retried/escalated.
+	//   `_retry`/`_escalated` are LOGICAL payload counters (NOT the lease `attempts` field — keeps crash accounting
+	//   intact, the plan's constraint); they ride the durable payload so a retry survives a crash/restart.
+	const recover = ( t, tr, reason ) => {
+		const p = t.payload || {};
+		if ( tr.retry && (p._retry || 0) < tr.retry ) {
+			store.move(t, tr.from, { payload: { _retry: (p._retry || 0) + 1, _failReason: String(reason) } });
+			c.retried++; return true;
+		}
+		if ( tr.escalate && !p._escalated ) {
+			store.move(t, tr.escalate, { payload: { _escalated: true, _failReason: String(reason) } });
+			c.escalated++; return true;
+		}
+		return false;
+	};
+	const lease = opts.lease || 30000, batch = opts.batch || 32, fuel = opts.maxSteps || 100000;
+
+	const byFrom = indexByFrom(net);
+	const gateFns = {};                                          // precompile each select's gates once
+	for ( const t of net.transitions ) if ( t.kind === 'select' )
+		gateFns[t.from] = (t.gates || []).map(( g ) => ({ to: g.to, fn: compileExpression(g.when, { empty: false }) }));
+
+	const c = { steps: 0, taskCalls: 0, memoHits: 0, bypass: 0, fanOut: 0, routed: 0, joins: 0, joinParked: 0, folds: 0, blamed: 0, retried: 0, escalated: 0, done: 0, failed: 0 };
+
+	while ( c.steps < fuel ) {
+		const toks = store.claim(runId, { limit: batch, lease });
+		if ( !toks.length ) break;                              // nothing claimable → fixpoint (or all in terminal places)
+		for ( const t of toks ) {
+			if ( c.steps >= fuel ) break;
+			c.steps++;
+			const tr = byFrom[t.placeId];
+			if ( !tr ) { store.fail(t, 'no transition from place ' + t.placeId); c.failed++; continue; }
+
+			if ( tr.kind === 'select' ) {
+				let to = tr.fallback;
+				for ( const g of gateFns[tr.from] ) if ( g.fn(( ref ) => resolveFact(t.payload, ref)) ) { to = g.to; break; }
+				store.move(t, to); c.routed++;
+				continue;
+			}
+
+			if ( tr.kind === 'map' ) {
+				const coll = resolveFact(t.payload, tr.over);
+				if ( !Array.isArray(coll) || !coll.length ) { store.move(t, tr.empty); continue; }
+				const places = coll.map(() => tr.bodyStart);
+				const p = t.payload || {};
+				// NESTED-fold: push this fan-out onto the group / cardinality / element-index STACKS (the join reads the
+				// TOP, the fold POPS one level). 1-level = a single-entry stack (the fold pops to empty → clean output).
+				// _join (REDUCING map only) + _onFail = the group recovery policy read by the C-fail ladder (failToken).
+				const groups = (p._groups || []).concat(String(t.id)), cards = (p._cards || []).concat(coll.length);
+				const base = tr.joinPlace ? { _n: coll.length, _join: tr.joinPlace, _onFail: tr.onFail || 'failfast' } : { _n: coll.length };
+				const payloads = coll.map(( elem, i ) => Object.assign({}, p, base,
+					{ [tr.elemKey]: elem, _i: i, _groups: groups, _cards: cards, _is: (p._is || []).concat(i) }));
+				store.move(t, places, { payloads }); c.fanOut += coll.length;
+				continue;
+			}
+
+			if ( tr.kind === 'join' ) {                          // the fan-IN: park-until-complete (Layer A is atomic)
+				const jp = t.payload || {};
+				// NESTED-fold: the group + cardinality come from the TOP of the stacks (1-level falls back to _n/parentId).
+				const expected = (jp._cards && jp._cards.length) ? jp._cards[jp._cards.length - 1] : jp._n;
+				const group = (jp._groups && jp._groups.length) ? jp._groups[jp._groups.length - 1] : (t.parentId == null ? null : String(t.parentId));
+				const res = store.joinArrive(t, tr.from, { expected, foldPlace: tr.foldPlace, failPlace: net.fail, mode: tr.onFail, group });
+				if ( res && res.ready ) c.joins++; else if ( res && res.failed ) c.failed++; else c.joinParked++;
+				continue;
+			}
+
+			if ( tr.kind === 'fold' ) {                          // reduce the collected siblings → one value
+				const sibs = (((t.payload || {})._siblings) || []).slice().sort(( a, b ) => ((a && a._i) || 0) - ((b && b._i) || 0));
+				let outPayload;
+				if ( tr.reduce && tr.reduce.task ) {             // a micro-task reconciliation join — memoized like a task
+					const key = foldKeyOf(tr, sibs);
+					let out;
+					if ( key != null && (out = store.memoGet(key)) !== undefined ) { c.memoHits++; }
+					else { out = (await runTask(tr.reduce.task, t)) || {}; c.taskCalls++; if ( key != null ) store.memoSet(key, out); else c.bypass++; }
+					outPayload = out.payload;
+				} else {                                         // a declared monoid — pure, order-independent, deterministic
+					outPayload = foldSiblings(sibs, tr.reduce);
+				}
+				// SURVIVORS: propagate the completeness markers so the folded VALUE and its incompleteness travel
+				// together (no silent partial — a downstream gate can read `_partial`/`_dropped`). failfast collectors
+				// carry no `_partial`, so this is inert for them.
+				const cp = t.payload || {};
+				if ( cp._partial !== undefined ) outPayload = Object.assign({}, outPayload, { _partial: cp._partial, _dropped: cp._dropped, _expected: cp._expected });
+				// NESTED-fold: if the siblings carried an OUTER level on their stack, POP one level (reconstructed from a
+				// sibling — the collector itself doesn't carry the stacks) and restore the OUTER element index so a
+				// non-commutative outer fold stays deterministic. The popped token flows to the outer join, where
+				// top(_groups) now selects the outer group. 1-level (single-entry stack) adds nothing → output stays clean.
+				const sibGroups = (sibs[0] && sibs[0]._groups) || [];
+				if ( sibGroups.length > 1 ) {
+					const _is = (sibs[0]._is || []).slice(0, -1);
+					outPayload = Object.assign({}, outPayload, { _groups: sibGroups.slice(0, -1), _cards: (sibs[0]._cards || []).slice(0, -1),
+						_is, _i: _is.length ? _is[_is.length - 1] : 0 });
+				}
+				store.move(t, tr.to, { payload: outPayload }); c.folds++;
+				continue;
+			}
+
+			// kind === 'task'
+			if ( tr.task == null ) { store.move(t, tr.to); continue; }   // no-op passthrough (enter/noop)
+			const key = keyOf(tr, t);
+			let out, hit = false;
+			if ( key != null && (out = store.memoGet(key)) !== undefined ) {
+				c.memoHits++; hit = true;                      // C5 replay — 0 model calls (cheap resume + amortization)
+			} else {
+				try { out = (await runTask(tr.task, t)) || {}; }   // runTask may be a real (async) LLM micro-task
+				catch ( e ) {                                      // an erroring task: recover via the C-fail ladder, else fail the token (never crashes the drain)
+					c.taskCalls++;
+					const reason = 'task-error:' + ((e && e.message) || e);
+					if ( recover(t, tr, reason) ) continue;
+					failToken(t, reason); c.failed++; continue;
+				}
+				c.taskCalls++;
+			}
+			// C-CONTRACT GUARD (assert-at-runtime, BEFORE commit — the §2 defeasible contract realized in the EXECUTE
+			// layer; addresses the adversary's #3: catch a wrong learned post BEFORE an irreversible downstream
+			// commit). A violation QUARANTINES the token (route to `fail` with a blame reason — a seed of C-fail), and
+			// a fresh violating output is NOT memoized (never cache a bad result). G1 frame-completeness + G2 oracle ride along.
+			if ( tr.contract ) {
+				const merged = Object.assign({}, t.payload, out.payload);
+				const v = assertStep(tr.contract, merged, Object.keys(out.payload || {}), { oracle: opts.oracle });
+				if ( !v.ok ) {                                     // a contract blame: same ladder (escalate is the meaningful recovery; a deterministic re-run re-blames, so retry is for non-det)
+					const reason = 'contract:' + v.blame.kind + (v.violations[0] && v.violations[0].detail ? ':' + v.violations[0].detail : '');
+					if ( recover(t, tr, reason) ) continue;
+					failToken(t, reason); c.blamed++; continue;
+				}
+			}
+			if ( !hit ) { if ( key != null ) store.memoSet(key, out); else c.bypass++; }
+			store.move(t, tr.to, { payload: out.payload, created: out.created });
+		}
+	}
+
+	const st = store.stats(runId);
+	c.done = st.done; c.failed = st.failed;
+	if ( c.steps >= fuel ) c.divergent = true;                 // fuel exhausted = a cutoff, NOT a semantic fixpoint
+	return c;
+}
+
+module.exports = { runFlow, resolveFact, defaultKeyOf };

package/lib/durable/xlate.js

@@ -0,0 +1,185 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * xlate — C-xlate v0 (the conception's "translation" step, component C-xlate). Compile ONE skynet method into a
+ * WORKFLOW-NET definition the durable executor (`checkpoint-store.js` + `interpreter.js`) runs over a stream of
+ * case records. This is the bridge from the BUILT/validated method (the belief-view, decidable, traceable) to
+ * the EXECUTE side (durable, mass, crash-resumable) — the §0.1 build/execute separation.
+ *
+ * The method SPEC is the compact declarative form of the Brick-1/3 example (`tests/integration/method-select`):
+ *   {
+ *     name,
+ *     select: { on?:[factKeys], rules:[{ when:"<expr over typed case facts>", method }], fallback:<methodName> },
+ *     methods: {
+ *       <name>: {
+ *         steps?: [{ task:"Ns::fn" }],            // a linear path of micro-tasks (the for/fold path)
+ *         map?:   { over:"<collKey>", body:[{ task }], elemKey?:"elem", empty?:"<place>",
+ *                   reduce?: { monoid:"sum"|… , key?, into? } | { task:"Ns::fold" } }   // Brick-1 fan-out + fan-IN
+ *       }
+ *     }
+ *   }
+ *
+ * compileMethod → a net { start, sinks, fail, transitions:[ ... ] } where a transition is one of:
+ *   { kind:'select', from, gates:[{ when, to }], fallback }   typed routing (selectCluster's gates → places)
+ *   { kind:'task',   from, task, to }                         a provider micro-task step (memoized by Layer B)
+ *   { kind:'map',    from, over, elemKey, bodyStart, empty }  unordered FAN-OUT, one child token per element
+ *   { kind:'join',   from, foldPlace }                        the cardinality JOIN (fan-in): park until all
+ *                                                             siblings arrive, then spawn ONE collector (Layer A)
+ *   { kind:'fold',   from, reduce, to }                       reduce the collected siblings → one value (Layer B)
+ *
+ * v0 scope (honest, per §4B / §9.2): select + linear task paths + map FAN-OUT, and — NEW — the fold-back /
+ * cardinality JOIN (`map.reduce`): the body's last step routes to a join place, the completing arrival spawns a
+ * collector, the fold reduces it (a declared monoid = pure/order-independent, or a micro-task). A `map` WITHOUT a
+ * `reduce` is the prior behaviour (each element flows to a sink independently — no rejoin).
+ */
+
+const START = 'start', DONE = 'done', FAIL = 'failed';
+
+function entryOf( method ) { return '@' + method; }          // a method's in-place (distinct from step/body places)
+
+/**
+ * Compile a method spec → a workflow-net def. Pure (no IO). Throws on a malformed spec.
+ */
+function compileMethod( spec ) {
+	if ( !spec || !spec.methods ) throw new Error('compileMethod: spec.methods is required');
+	const transitions = [];
+	const sel = spec.select;
+
+	if ( sel ) {
+		const gates = (sel.rules || []).map(( r ) => {
+			if ( !r.when || !r.method ) throw new Error('compileMethod: a select rule needs { when, method }');
+			if ( !spec.methods[r.method] ) throw new Error(`compileMethod: select rule routes to unknown method "${r.method}"`);
+			return { when: r.when, to: entryOf(r.method) };
+		});
+		if ( sel.fallback && !spec.methods[sel.fallback] ) throw new Error(`compileMethod: fallback method "${sel.fallback}" is undefined`);
+		transitions.push({ id: 'select', from: START, kind: 'select', gates, fallback: sel.fallback ? entryOf(sel.fallback) : FAIL });
+	}
+
+	for ( const m of Object.keys(spec.methods) ) compileBody(m, spec.methods[m], transitions);
+
+	// with no select, the single method is the entry — wire start → its in-place via a no-op task.
+	if ( !sel ) {
+		const names = Object.keys(spec.methods);
+		if ( names.length !== 1 ) throw new Error('compileMethod: a spec without a `select` must have exactly one method');
+		transitions.unshift({ id: 'enter', from: START, kind: 'task', task: null, to: entryOf(names[0]) });
+	}
+
+	const net = { start: START, sinks: [DONE], fail: FAIL, transitions };
+	const issues = validateNet(net);
+	if ( issues.length ) throw new Error('compileMethod: malformed net — ' + issues.join('; '));
+	return net;
+}
+
+// emit a task transition, plus — when the step declares `escalate` — an ESCALATION place: a bigger
+// micro-task at `<from>@escalate` whose `to` rejoins the SAME downstream place, so a recovered shard
+// flows on as if the original had succeeded (the C-fail escalate rung). `retry` (a bounded re-exec
+// count, for transient/non-det tasks) rides the transition itself. ZERO Layer-A.
+function emitTask( transitions, id, from, step, to ) {
+	step = step || {};
+	const t = { id, from, kind: 'task', task: step.task != null ? step.task : null, to, contract: step.contract };
+	if ( step.retry ) t.retry = step.retry;
+	if ( step.escalate ) {
+		const escPlace = from + '@escalate';
+		t.escalate = escPlace;
+		transitions.push(t);
+		transitions.push({ id: id + '.esc', from: escPlace, kind: 'task',
+			task: typeof step.escalate === 'string' ? step.escalate : step.escalate.task, to, contract: step.contract });
+		return;
+	}
+	transitions.push(t);
+}
+
+// emit a map fan-out + body + (optional) fan-IN fold, routing the final fold to `toPlace`. RECURSIVE: a body step
+// may be a linear task OR a NESTED map (`{ map:{…} }`) — the inner fold's `to` rejoins the OUTER flow (its next body
+// place / the outer join). v0 ships + tests depth 2 (the runtime group/_i stacks are depth-agnostic).
+function emitMap( ns, map, fromPlace, toPlace, transitions ) {
+	if ( !map.over ) throw new Error(`compileMethod: map "${ns}" needs an \`over\` collection key`);
+	const reduce = map.reduce;
+	const joinPlace = ns + '@join', foldPlace = ns + '@fold';
+	const bodyEnd = reduce ? joinPlace : toPlace;            // with a reduce, the body REJOINS at the join place
+	const bsteps = map.body || [];
+	const bodyStart = bsteps.length ? (ns + '@body') : bodyEnd;
+	transitions.push({ id: ns + '.map', from: fromPlace, kind: 'map', over: map.over, elemKey: map.elemKey || 'elem',
+		bodyStart, empty: map.empty || (reduce ? foldPlace : toPlace), joinPlace: reduce ? joinPlace : undefined,
+		onFail: reduce ? reduce.onFail : undefined });
+	let bp = bodyStart;
+	bsteps.forEach(( step, i ) => {
+		const stepTo = i === bsteps.length - 1 ? bodyEnd : (ns + '@body#' + (i + 1));
+		if ( step && step.map ) emitMap(ns + '@body.m' + i, step.map, bp, stepTo, transitions);   // a NESTED map-reduce
+		else emitTask(transitions, ns + '.body.s' + i, bp, step, stepTo);
+		bp = stepTo;
+	});
+	if ( reduce ) {                                          // the fan-IN: park-until-complete → spawn collector → fold
+		transitions.push({ id: ns + '.join', from: joinPlace, kind: 'join', foldPlace, onFail: reduce.onFail });
+		// a post-fold completeness handler — a linear `then` chain the fold routes to instead of `toPlace`. REQUIRED
+		// for a 'survivors' fold (it must not route a possibly-partial aggregate straight to a sink; validateNet
+		// enforces it — the no-silent-partial invariant). A `then` step can carry a `contract` reading `_partial`.
+		const thenSteps = reduce.then || [];
+		const foldTo = thenSteps.length ? (ns + '@then') : toPlace;
+		transitions.push({ id: ns + '.fold', from: foldPlace, kind: 'fold', reduce, to: foldTo, onFail: reduce.onFail });
+		let tp = ns + '@then';
+		thenSteps.forEach(( step, i ) => {
+			const stepTo = i === thenSteps.length - 1 ? toPlace : (ns + '@then#' + (i + 1));
+			emitTask(transitions, ns + '.then.s' + i, tp, step, stepTo);
+			tp = stepTo;
+		});
+	}
+}
+
+function compileBody( m, def, transitions ) {
+	def = def || {};
+	const steps = def.steps || [];
+	let place = entryOf(m);
+
+	steps.forEach(( step, i ) => {
+		const last = i === steps.length - 1 && !def.map;
+		const to = last ? DONE : (m + '#' + (i + 1));
+		emitTask(transitions, m + '.s' + i, place, step, to);
+		place = to;
+	});
+
+	if ( def.map ) emitMap(m, def.map, place, DONE, transitions);
+	else if ( !steps.length ) transitions.push({ id: m + '.noop', from: place, kind: 'task', task: null, to: DONE });  // a degenerate empty method
+}
+
+/**
+ * Structural lint (validate the STRUCTURE, not the grammar — methodology §0.6): every place a transition routes
+ * TO must be a sink/fail or have its own outgoing transition (no dangling place that strands a token); no two
+ * transitions share a `from` place (the marking is 1-out per place — `select` is the only multi-way, via gates).
+ * @returns string[] of issues (empty = sound).
+ */
+function validateNet( net ) {
+	const issues = [], froms = new Set(), terminals = new Set([].concat(net.sinks || [], net.fail || []));
+	const targets = [];
+	for ( const t of net.transitions ) {
+		if ( froms.has(t.from) ) issues.push(`two transitions leave place "${t.from}" (marking is 1-out per place)`);
+		froms.add(t.from);
+		if ( t.kind === 'select' ) { (t.gates || []).forEach(( g ) => targets.push(g.to)); if ( t.fallback ) targets.push(t.fallback); }
+		else if ( t.kind === 'map' ) { targets.push(t.bodyStart); targets.push(t.empty); }
+		else if ( t.kind === 'join' ) targets.push(t.foldPlace);
+		else { targets.push(t.to); if ( t.escalate ) targets.push(t.escalate); }   // task / fold (+ optional escalation place)
+	}
+	for ( const tgt of targets ) if ( !terminals.has(tgt) && !froms.has(tgt) )
+		issues.push(`place "${tgt}" is routed-to but has no outgoing transition and is not a sink`);
+	if ( !froms.has(net.start) ) issues.push(`the start place "${net.start}" has no outgoing transition`);
+	// HARD lint (the no-silent-partial invariant): a 'survivors' fold may emit an INCOMPLETE aggregate (some shards
+	// dropped), so it MUST route to a completeness gate (a `reduce.then` handler reading `_partial`/`_dropped`), never
+	// straight to a sink where a partial would pass as complete. Stricter than the general uncontracted=warning stance.
+	for ( const t of net.transitions ) if ( t.kind === 'fold' && t.onFail === 'survivors' && terminals.has(t.to) )
+		issues.push(`a 'survivors' fold ("${t.id}") routes directly to a sink — it must be followed by a completeness gate (declare \`reduce.then\` reading _partial/_dropped); the no-silent-partial invariant`);
+	return issues;
+}
+
+// index transitions by their `from` place (one per place) — the interpreter's dispatch table.
+function indexByFrom( net ) {
+	const byFrom = {};
+	for ( const t of net.transitions ) byFrom[t.from] = t;
+	return byFrom;
+}
+
+module.exports = { compileMethod, validateNet, indexByFrom, entryOf, places: { START, DONE, FAIL } };