wingfoil 0.2.1 → 0.3.0

package/dist/workflow/deduce.js

@@ -0,0 +1,1109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLAN_TYPE = exports.OPEN_PLAN_STATUSES = exports.NO_ITERATION_NOTE = exports.W_INSTANCE_WORKFLOW_UNKNOWN = exports.W_UNRESOLVED_TOKEN = exports.W_MEMORY_INVALID_STATE = exports.W_UNCOMMITTED_INPUTS = void 0;
+exports.uncommittedInputDiagnostic = uncommittedInputDiagnostic;
+exports.declaresState = declaresState;
+exports.deduceWorkflowState = deduceWorkflowState;
+exports.resolveInstanceRef = resolveInstanceRef;
+const query_1 = require("../memory/query");
+const state_machine_1 = require("../memory/state-machine");
+const validation_1 = require("../validation");
+// The modules, not the `../core` barrel: `src/core` imports this one.
+const workflow_diagnostics_1 = require("../core/workflow-diagnostics");
+const workflow_exit_state_1 = require("../core/workflow-exit-state");
+const bindings_1 = require("./bindings");
+const schema_1 = require("./schema");
+/** `W_UNCOMMITTED_INPUTS` (`spec-017` §1.2): a deduction input differs from `HEAD`; the answer is `HEAD`'s. */
+exports.W_UNCOMMITTED_INPUTS = 'W_UNCOMMITTED_INPUTS';
+/**
+ * The `W_UNCOMMITTED_INPUTS` diagnostic of one dirty input path (`spec-017` §1.2; one per path, task-198).
+ * The deduction builds its own through here, and so does `agent list --past`, which runs no deduction and
+ * emits the code itself under the same rule (`spec-016` §5, task-240), so the two cannot word it apart.
+ */
+function uncommittedInputDiagnostic(path) {
+    return {
+        code: exports.W_UNCOMMITTED_INPUTS,
+        severity: 'warning',
+        file: path,
+        path: '',
+        message: `uncommitted change to a deduction input, not read (the answer is computed from HEAD): ${path}`,
+    };
+}
+/** `W_MEMORY_INVALID_STATE` (`spec-017` §1.4, P4.13 sc. 3): a status its type's machine does not declare. */
+exports.W_MEMORY_INVALID_STATE = 'W_MEMORY_INVALID_STATE';
+/** `W_UNRESOLVED_TOKEN` (`spec-017` §4.1): a token with no value on the element it resolves against. */
+exports.W_UNRESOLVED_TOKEN = 'W_UNRESOLVED_TOKEN';
+/** `W_INSTANCE_WORKFLOW_UNKNOWN` (`spec-017` §2): an open plan names a workflow the registry does not load. */
+exports.W_INSTANCE_WORKFLOW_UNKNOWN = 'W_INSTANCE_WORKFLOW_UNKNOWN';
+/** The note of an `iterate_over` phase no candidate was counted for (`spec-017` §4.6, P4.16 sc. 3). */
+exports.NO_ITERATION_NOTE = 'no elements matched the iterate_over filter';
+/** The plan statuses of an open instance (`spec-017` §3.2). */
+exports.OPEN_PLAN_STATUSES = ['draft', 'active'];
+/** The Memory type that records a workflow instance (`spec-017` §3.1, `dl-019`). */
+exports.PLAN_TYPE = 'plan';
+/** Code-unit order (`Array.prototype.sort`'s default), as a comparator. */
+function compareText(a, b) {
+    return Number(a > b) - Number(a < b);
+}
+/**
+ * A `memory.yaml` type `path` pattern as a whole-path regular expression. A token in the file name is one
+ * name; a token in a directory is one or more directories, since a value such as the plan's `{scope}`
+ * nests (`rl-v1/rel-v0.3`, `.wingfoil/memory.yaml` `plan.path`).
+ */
+function pathPatternRegExp(pattern) {
+    const slash = pattern.lastIndexOf('/');
+    const convert = (part, token) => part
+        .split(/\{[^{}]+\}/)
+        .map((piece) => piece.replace(/[.*+?^$()|[\]\\]/g, '\\$&'))
+        .join(token);
+    return new RegExp(`^${convert(pattern.slice(0, slash + 1), '[^/]+(?:/[^/]+)*')}${convert(pattern.slice(slash + 1), '[^/]+')}$`);
+}
+/** A frontmatter value as a non-blank string, or `null`. */
+function scalarText(value) {
+    if (typeof value === 'string')
+        return value.trim() === '' ? null : value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return null;
+}
+function hasType(memoryYaml, type) {
+    return memoryYaml !== null && Object.prototype.hasOwnProperty.call(memoryYaml.types, type);
+}
+/**
+ * The elements of the snapshot, and the `W_MEMORY_*` reports of the documents left out (§1.4): no
+ * frontmatter, no `type`, a type `memory.yaml` does not declare, no `id`, no `status` —
+ * `W_MEMORY_UNREADABLE`; a status the type's machine does not declare — `W_MEMORY_INVALID_STATE`,
+ * decided by `validateFrontmatterState`, the rule every Memory verb applies (P4.11).
+ */
+function readElements(snapshot) {
+    const elements = [];
+    const diagnostics = [...snapshot.scanDiagnostics];
+    const { memoryYaml } = snapshot;
+    const typePaths = Object.values(memoryYaml?.types ?? {}).map((entry) => pathPatternRegExp(entry.path));
+    for (const document of snapshot.documents) {
+        const { path, frontmatter } = document;
+        const unreadable = (reason) => {
+            diagnostics.push((0, query_1.memoryUnreadableDiagnostic)(path, reason));
+        };
+        if (Object.keys(frontmatter).length === 0) {
+            // A file on no type's path is not a Memory document at all — the `X_*` plans `dl-019` grandfathers at
+            // the top of `docs/05_plans/` — and is left out silently; one on a type's path is a document §1.4 reports.
+            if (typePaths.some((pattern) => pattern.test(path)))
+                unreadable('no frontmatter');
+            continue;
+        }
+        const type = scalarText(frontmatter['type']);
+        if (type === null) {
+            unreadable("no 'type' field");
+            continue;
+        }
+        if (!hasType(memoryYaml, type)) {
+            unreadable(`type '${type}' is not declared in memory.yaml`);
+            continue;
+        }
+        const id = scalarText(frontmatter['id']);
+        if (id === null) {
+            unreadable("no 'id' field");
+            continue;
+        }
+        const status = scalarText(frontmatter['status']);
+        if (status === null) {
+            unreadable("no 'status' field");
+            continue;
+        }
+        try {
+            (0, state_machine_1.validateFrontmatterState)((0, state_machine_1.resolveStateMachine)(memoryYaml, type), type, status, path);
+        }
+        catch (error) {
+            const issue = error.issues[0];
+            diagnostics.push({ code: exports.W_MEMORY_INVALID_STATE, severity: 'warning', file: path, path: 'status', message: `${issue.message} in ${path}` });
+            continue;
+        }
+        elements.push({ type, id, status, path, frontmatter });
+    }
+    // By path; a stable sort keeps one file's reports in the order they were made.
+    diagnostics.sort((a, b) => compareText(a.file, b.file));
+    return { elements, diagnostics };
+}
+/** `<type>:<id>` of an element scope, `<collection>#<key>` of a collection-entry scope (`spec-017` §4.8, §4.9). */
+function scopeKey(scope) {
+    if ('item' in scope)
+        return `${scope.item.collection}#${scope.item.key}`;
+    return `${scope.element.type}:${scope.element.id}`;
+}
+function refOf(element) {
+    return { type: element.type, id: element.id, status: element.status };
+}
+/** Ascending `(type, id)` (`spec-017` §1.3, "elements a step created or awaits"). */
+function compareRefs(a, b) {
+    return compareText(a.type, b.type) || compareText(a.id, b.id);
+}
+/** The scope a step runs on: its innermost frame's element or collection entry (§4.9). */
+function scopeOf(frames) {
+    const frame = frames[frames.length - 1];
+    if (frame === undefined)
+        return null;
+    if (frame.kind === 'item')
+        return { item: { collection: frame.collection, key: frame.key } };
+    return frame.element === null ? null : { element: refOf(frame.element) };
+}
+const TOKEN_RE = /\{([^{}]+)\}/g;
+/**
+ * A collection reference (`dna:<path>`, `bindings:<name>`, `element:<field>`) rather than a Memory type
+ * (`spec-003` § "Collections"; `element:` since task-230).
+ */
+const COLLECTION_REF_RE = /^(dna|bindings|element):/;
+/** A list read from a frontmatter field of the innermost bound element (`spec-017` §4.6, task-230). */
+const ELEMENT_COLLECTION = 'element:';
+/**
+ * The entries of an `element:<field>` collection (`spec-017` §4.6): the list in `<field>` of the innermost
+ * bound element, labelled `<type>:<id>/<field>`; an explicit `[]` has no entries. No bound element, an absent
+ * field, a value that is not a list, or an entry key problem (`collectionKeyIssues`, the rule `bindings.yaml` collections
+ * are loaded under) leaves the entries undecided, with the reason.
+ */
+function elementCollection(reference, frames) {
+    const field = reference.slice(ELEMENT_COLLECTION.length);
+    const frame = [...frames].reverse().find((candidate) => candidate.kind === 'element');
+    if (frame === undefined)
+        return { reason: `collection '${reference}' has no element in scope` };
+    if (frame.element === null)
+        return { reason: `collection '${reference}' has no ${frame.type} element bound` };
+    const ref = `${frame.element.type}:${frame.element.id}`;
+    const raw = frame.element.frontmatter[field];
+    // An absent field is undecided, not empty (task-230 review F1): a release planned before its waves were declared
+    // must not read as a finished implementation. An explicit `[]` is a declared empty list (vacuous, §4.6).
+    if (raw === undefined || raw === null)
+        return { reason: `collection '${reference}' of ${ref} has no field '${field}'` };
+    if (!Array.isArray(raw))
+        return { reason: `collection '${reference}' of ${ref} is not a list` };
+    const entries = raw;
+    const issue = (0, bindings_1.collectionKeyIssues)(entries)[0];
+    if (issue !== undefined)
+        return { reason: `collection '${reference}' of ${ref} entry ${issue.index}: ${issue.message}` };
+    return { label: `${ref}/${field}`, entries };
+}
+/** `{item}` / `{item.<field>}` against the innermost collection entry (§4.1, `spec-003` § "Collections"). */
+function itemValue(inner, frames) {
+    const frame = [...frames].reverse().find((candidate) => candidate.kind === 'item');
+    if (frame === undefined)
+        return { reason: 'no collection entry in scope' };
+    if (inner === 'item')
+        return { value: frame.key };
+    const field = inner.slice('item.'.length);
+    const raw = typeof frame.entry === 'object' && frame.entry !== null ? scalarText(frame.entry[field]) : null;
+    return raw === null ? { reason: `${frame.collection}#${frame.key} has no value for '${field}'` } : { value: raw };
+}
+/**
+ * Substitute the `{…}` tokens of `text` against `frames` (innermost last), as whole values, never
+ * evaluated (`dl-090` Q3 (a)): `{<type>.<field>}` against the nearest element of `<type>`; `{id}`,
+ * `{<field>}` and `{element.<field>}` against the innermost element; `{item}` and `{item.<field>}`
+ * against the innermost collection entry.
+ */
+function resolveTokens(text, frames) {
+    const unresolved = [];
+    let pending = false;
+    const elementFrames = frames.filter((frame) => frame.kind === 'element');
+    const value = text.replace(TOKEN_RE, (token, inner) => {
+        let frame;
+        let field;
+        const dot = inner.indexOf('.');
+        if (inner === 'item' || inner.startsWith('item.')) {
+            const item = itemValue(inner, frames);
+            if ('value' in item)
+                return item.value;
+            unresolved.push({ token, reason: item.reason });
+            return token;
+        }
+        if (dot === -1) {
+            frame = elementFrames[elementFrames.length - 1];
+            field = inner;
+        }
+        else {
+            const head = inner.slice(0, dot);
+            field = inner.slice(dot + 1);
+            frame = head === 'element' ? elementFrames[elementFrames.length - 1] : [...elementFrames].reverse().find((candidate) => candidate.type === head);
+        }
+        if (frame === undefined) {
+            unresolved.push({ token, reason: 'no element in scope' });
+            return token;
+        }
+        if (frame.element === null) {
+            if (frame.pending)
+                pending = true;
+            else
+                unresolved.push({ token, reason: `no ${frame.type} element is bound` });
+            return token;
+        }
+        const raw = field === 'id' ? frame.element.id : scalarText(frame.element.frontmatter[field]);
+        if (raw === null) {
+            unresolved.push({ token, reason: `${frame.element.type}:${frame.element.id} has no value for '${field}'` });
+            return token;
+        }
+        return raw;
+    });
+    return { value: unresolved.length === 0 && !pending ? value : null, unresolved, pending };
+}
+// --- Evidence (§4.3) ---------------------------------------------------------------------------------
+/** The untyped verbs that, before any `memory.add` and outside a selection, move the bound element (`spec-003` § "Evidence"). */
+const STATE_VERBS = ['memory.submit', 'memory.approve', 'element.set_state'];
+/** The untyped tokens that act on the created elements, the selection or the bound element (`spec-017` §4.2). */
+const UNTYPED_TARGET_VERBS = ['memory.submit', 'memory.approve', 'memory.reject', 'memory.deprecate', 'element.set_state', 'element.set_release'];
+/** A frontmatter value as a list of strings (absent: none). */
+function asStrings(value) {
+    if (value === undefined || value === null)
+        return [];
+    return (Array.isArray(value) ? value : [value]).map(String);
+}
+const TYPED_SET_STATE_RE = /^([a-z][a-z0-9-]*)\.set_state$/;
+/** Whether `phase` declares `state` evidence on an element of `boundType` (`spec-003` § "Evidence", `spec-017` §4.2). */
+function declaresState(phase, boundType) {
+    if (boundType === null)
+        return false;
+    const selection = phase.where !== undefined && phase.iterate_over === undefined;
+    let added = false;
+    for (const action of phase.actions ?? []) {
+        const name = (0, bindings_1.tokenName)(action);
+        if (name === 'memory.add') {
+            added = true;
+            continue;
+        }
+        if (STATE_VERBS.includes(name) && !added && !selection)
+            return true;
+        if (TYPED_SET_STATE_RE.exec(name)?.[1] === boundType)
+            return true;
+    }
+    return false;
+}
+/** Whether `status` is at or after `exit` in `machine`'s `sequence` (§4.3 `state`, §4.4). */
+function atOrAfter(machine, status, exit) {
+    const at = machine.sequence.indexOf(status);
+    const target = machine.sequence.indexOf(exit);
+    if (at === -1 || target === -1)
+        return status === exit;
+    return at >= target;
+}
+/** `spec-003`'s `where` match rule: equal, member, or (for a list field) a shared element. Absent reads as `""`. */
+function matches(field, wanted) {
+    const have = field === undefined || field === null ? [''] : Array.isArray(field) ? field.map(String) : [String(field)];
+    return have.some((value) => wanted.includes(value));
+}
+/** The history of an instance with nothing in its walk. */
+const EMPTY_HISTORY = { records: [], links: [], reentries: [] };
+/** `<type>:<id>` of an element. */
+function keyOf(element) {
+    return `${element.type}:${element.id}`;
+}
+/** Ascending `(type, id)` (`spec-017` §1.3, "elements a step created"). */
+function byTypeThenId(a, b) {
+    return compareText(a.type, b.type) || compareText(a.id, b.id);
+}
+/** The newest of the re-entries that reach a step (the smallest walk position), for display; `null` for none. */
+function newest(reentries) {
+    return reentries.reduce((best, entry) => (best === null || entry.position < best.position ? entry : best), null);
+}
+/**
+ * The carried elements that await a phase's approval (`spec-017` §5.1): the targets of its actions — the bound
+ * element, the selection, the created and the run elements; a `sync_state` is never a carrier (§4.2) — that sit
+ * in a gate state the phase holds, each once, ascending `(type, id)`.
+ */
+function awaitingElements(actions, exit) {
+    const found = new Map();
+    for (const action of actions) {
+        if (action.target === 'none' || (0, bindings_1.tokenName)(action.token).endsWith('.sync_state'))
+            continue;
+        for (const target of action.targets) {
+            if (exit.held.some((held) => held.type === target.type && held.gate === target.status))
+                found.set(keyOf(target), target);
+        }
+    }
+    return [...found.values()].sort(compareRefs);
+}
+/** The read-only context of one deduction. */
+class Deducer {
+    snapshot;
+    byName = new Map();
+    fileOf = new Map();
+    tree;
+    elements;
+    /** The walk's child links (the inverse of `snapshot.parents`), built on first use. */
+    children = null;
+    /** The strict descendants in the walk of each re-entry commit asked about. */
+    descendantsOf = new Map();
+    constructor(snapshot, elements) {
+        this.snapshot = snapshot;
+        // Names are unique: the registry refuses a duplicate at load time (`spec-003`), so no entry is overwritten.
+        snapshot.workflows.forEach((workflow, i) => {
+            this.byName.set(workflow.name, workflow);
+            this.fileOf.set(workflow.name, snapshot.workflowFiles[i]);
+        });
+        this.tree = new Set(snapshot.tree);
+        this.elements = elements;
+    }
+    workflow(name) {
+        return this.byName.get(name);
+    }
+    /** The first element of `type` with `id`, in path order. */
+    find(type, id) {
+        return this.elements.find((element) => element.type === type && element.id === id) ?? null;
+    }
+    /** The first element of any type with `id`, in path order. */
+    findAny(id) {
+        return this.elements.find((element) => element.id === id) ?? null;
+    }
+    plans() {
+        return this.elements.filter((element) => element.type === exports.PLAN_TYPE);
+    }
+    exists(path) {
+        if (!path.endsWith('/'))
+            return this.tree.has(path);
+        return this.snapshot.tree.some((file) => file.startsWith(path));
+    }
+    /**
+     * The first state of `type`. Called only to bind an instance, i.e. for a plan element, which exists only
+     * when `memory.yaml` does; and a workflow's `element` type is one `memory.yaml` declares, or the registry
+     * refuses it (`E_WORKFLOW_ELEMENT_TYPE_UNKNOWN`).
+     */
+    firstState(type) {
+        return (0, state_machine_1.resolveStateMachine)(this.snapshot.memoryYaml, type).sequence[0];
+    }
+    /** What the walk of the instance started at `startCommit` holds (§4.8). */
+    history(startCommit) {
+        return this.snapshot.history.get(startCommit) ?? EMPTY_HISTORY;
+    }
+    /**
+     * The elements an instance's steps created (§4.8 linkage): the add commits of its walk whose
+     * `WingFoil-Instance` is the instance and whose `WingFoil-Step` is one of `steps` (every step when
+     * `null`), each element once, ascending `(type, id)`. An element `HEAD` does not hold is left out.
+     */
+    createdBy(instanceId, startCommit, steps) {
+        const found = new Map();
+        for (const link of this.history(startCommit).links) {
+            if (link.instance !== instanceId || (steps !== null && !steps.includes(link.step)))
+                continue;
+            const element = this.find(link.type, link.id);
+            if (element !== null)
+                found.set(keyOf(element), element);
+        }
+        return [...found.values()].sort(byTypeThenId);
+    }
+    /**
+     * The commit that put `element` in its current status (§4.8, `state` after a re-entry): the latest
+     * transition commit naming it that left that status — its bracket's `<to>`, or the file's status at a
+     * bracketless `add` / `submit` (task-281, `bug-300`) — else the latest commit in the walk that changed its
+     * file; `null` (older than anything in the walk) when neither.
+     */
+    stateCommit(element) {
+        const named = this.snapshot.transitions.find((entry) => entry.type === element.type && entry.id === element.id && entry.to === element.status);
+        return named?.commit ?? this.snapshot.lastChanges.get(keyOf(element))?.commit ?? null;
+    }
+    /** The strict descendants of `commit` within the walk, through its parent links (§4.8, review F1). */
+    descendants(commit) {
+        const known = this.descendantsOf.get(commit);
+        if (known !== undefined)
+            return known;
+        if (this.children === null) {
+            this.children = new Map();
+            for (const [child, parents] of this.snapshot.parents) {
+                for (const parent of parents)
+                    this.children.set(parent, [...(this.children.get(parent) ?? []), child]);
+            }
+        }
+        const found = new Set();
+        const pending = [...(this.children.get(commit) ?? [])];
+        while (pending.length > 0) {
+            const next = pending.pop();
+            if (found.has(next))
+                continue;
+            found.add(next);
+            pending.push(...(this.children.get(next) ?? []));
+        }
+        this.descendantsOf.set(commit, found);
+        return found;
+    }
+    /** Whether `commit` is newer than every re-entry in `reentries`: a strict descendant of each (§4.8). */
+    newerThan(commit, reentries) {
+        return reentries.every((reentry) => commit !== null && this.descendants(reentry.commit).has(commit));
+    }
+    /**
+     * The re-entry cutoff of each phase of a pass of `workflow` on `element` (§4.8 re-entries, §5.2): for
+     * every re-entry of the element in the instance's walk, the phase whose gate state was its `<from>` —
+     * the first phase that holds that gate (§5.1) and declares a `fallback` — names a `fallback.step`; from
+     * that phase onward the `record` and `state` evidence counts only if newer than the re-entry — a
+     * descendant of its commit. A phase reached by several re-entries keeps them all, and its evidence must
+     * descend from each; `inherited` is what reaches the including phase. A
+     * re-entry from a state no phase holds as a gate with a fallback reaches no phase: the element's state
+     * alone tells the deduction where the pass stands.
+     */
+    cutoffs(startCommit, workflow, exits, element, inherited) {
+        const out = workflow.phases.map(() => [...inherited]);
+        if (element === null)
+            return out;
+        for (const reentry of this.history(startCommit).reentries) {
+            if (reentry.type !== element.type || reentry.id !== element.id)
+                continue;
+            const gate = workflow.phases.findIndex((phase, p) => phase.fallback !== undefined && exits[p].held.some((held) => held.type === reentry.type && held.gate === reentry.from));
+            if (gate === -1)
+                continue;
+            // A `fallback.step` naming no phase is refused at load time (`E_PHASE_FALLBACK_STEP_UNKNOWN`, spec-003).
+            const fallback = workflow.phases[gate].fallback;
+            const from = workflow.phases.findIndex((phase) => phase.name === fallback.step);
+            // Each reaching re-entry names the fallback that took it, which the re-entered step reports (§5.2).
+            const reaching = { ...reentry, fallback: { step: fallback.step, setState: fallback.set_state ?? null } };
+            for (let q = from; q < out.length; q += 1)
+                out[q].push(reaching);
+        }
+        return out;
+    }
+    /**
+     * Run a workflow on `frames`, from `start` (§4.4), under `trail`; `inherited` are the re-entries reaching
+     * the including phase (§4.8). In declared order, a phase is complete
+     * when its evidence is; a live query (§4.7) is also complete, and an optional phase (§4.10) skipped,
+     * when a later phase is complete other than vacuously; the first other phase is current and gives the
+     * frontier. A phase is evaluated only when one of these rules needs it, at most once.
+     */
+    run(instanceId, startCommit, workflow, frames, start, trail, inherited = []) {
+        // `memory.yaml` is present: a workflow runs only for an open plan, an element of a declared type.
+        const exits = (0, workflow_exit_state_1.workflowExitStates)(workflow, this.snapshot.memoryYaml, start, this.byName);
+        const last = frames[frames.length - 1];
+        // A collection entry has no re-entries: only an element scope cuts evidence (§4.8).
+        const cutoffs = this.cutoffs(startCommit, workflow, exits, last?.kind === 'element' ? last.element : null, inherited);
+        const scope = scopeOf(frames);
+        const evals = [];
+        const evaluated = (p) => (evals[p] ??= this.evaluate(instanceId, startCommit, workflow, p, frames, exits[p], [...trail, { workflow: workflow.name, phase: workflow.phases[p].name, scope }], scope, cutoffs[p]));
+        const closedFrom = (p) => {
+            for (let q = p + 1; q < workflow.phases.length; q += 1) {
+                const later = evaluated(q);
+                if (later.complete && !later.vacuous)
+                    return true;
+            }
+            return false;
+        };
+        const phases = [];
+        let frontier = [];
+        let diagnostics = [];
+        const late = [];
+        let current = false;
+        let progressed = false;
+        workflow.phases.forEach((phase, p) => {
+            if (current) {
+                phases.push({ phase: phase.name, state: 'pending' });
+                return;
+            }
+            const evaluation = evaluated(p);
+            if (evaluation.complete) {
+                phases.push(progress(phase.name, 'complete', evaluation.vacuous, evaluation.iterations));
+                late.push(...evaluation.late);
+                progressed ||= !evaluation.vacuous;
+                return;
+            }
+            if (evaluation.liveQuery && closedFrom(p)) {
+                const { iterations } = evaluation;
+                const closed = iterations === undefined ? undefined : { eligible: 0, entered: 0, complete: iterations.complete, late: evaluation.closed.count };
+                phases.push(progress(phase.name, 'complete', false, closed));
+                late.push(...evaluation.closed.late);
+                progressed = true;
+                return;
+            }
+            if (phase.optional && closedFrom(p)) {
+                phases.push({ phase: phase.name, state: 'skipped' });
+                return;
+            }
+            current = true;
+            phases.push(progress(phase.name, 'current', false, evaluation.iterations));
+            late.push(...evaluation.late);
+            frontier = [...evaluation.frontier];
+            diagnostics = [...evaluation.diagnostics];
+            // An optional current phase is reported together with the phases up to the next non-optional one (§4.10).
+            for (let q = p + 1; phase.optional && q < workflow.phases.length; q += 1) {
+                const later = evaluated(q);
+                if (later.complete)
+                    continue;
+                frontier.push(...later.frontier);
+                diagnostics.push(...later.diagnostics);
+                if (!workflow.phases[q].optional)
+                    break;
+            }
+        });
+        return { complete: !current, progressed, phases, frontier, diagnostics, late };
+    }
+    /** Evaluate phase `p` on its own: a plain `include`, an `iterate_over` or a leaf step. */
+    evaluate(instanceId, startCommit, workflow, p, frames, exit, trail, scope, reentries) {
+        const phase = workflow.phases[p];
+        // The include resolves: the registry refuses one naming no loaded workflow (`spec-003` loader rows).
+        if (phase.include !== undefined && phase.iterate_over !== undefined) {
+            return this.iterate(instanceId, startCommit, workflow, p, frames, exit, trail, scope, reentries);
+        }
+        // A plain `include` (§4.5): the sub runs on the same element, from the state this phase starts in.
+        if (phase.include !== undefined) {
+            const sub = this.byName.get(phase.include);
+            const result = this.run(instanceId, startCommit, sub, frames, { boundType: sub.element ?? exit.boundType, state: exit.entry, instance: false }, trail, reentries);
+            return {
+                complete: result.complete,
+                vacuous: result.complete && !result.progressed,
+                liveQuery: false,
+                frontier: result.frontier,
+                diagnostics: result.diagnostics,
+                late: result.late,
+                closed: { late: [], count: 0 },
+            };
+        }
+        const leaf = this.leaf(instanceId, startCommit, workflow, p, frames, exit, trail, scope, reentries);
+        const { kinds, missing } = leaf.step.evidence;
+        // A phase with `approval:` also needs no carried element to await it (§4.3, §5.1).
+        const complete = missing.length === 0 && (leaf.step.approval?.elements.length ?? 0) === 0;
+        const selection = kinds.includes('selection');
+        return {
+            complete,
+            // A selection that matches nothing, with no other evidence than an empty `created` (§4.7).
+            vacuous: complete && selection && leaf.step.created.length === 0 && kinds.every((kind) => kind === 'selection' || kind === 'created'),
+            liveQuery: selection,
+            frontier: [leaf.step],
+            diagnostics: leaf.diagnostics,
+            late: [],
+            closed: { late: leaf.selected, count: leaf.selected.length },
+        };
+    }
+    /** The `where` values of `phase`, resolved against `frames`, by key in byte order; `null` when a token has no value. */
+    wanted(phase, p, frames, report) {
+        const wanted = [];
+        let decidable = true;
+        for (const key of Object.keys(phase.where ?? {}).sort()) {
+            const raw = phase.where[key];
+            const values = (Array.isArray(raw) ? raw : [raw]).map((value) => {
+                if (typeof value !== 'string')
+                    return String(value);
+                const resolved = resolveTokens(value, frames);
+                report(`phases[${p}].where.${key}`, resolved);
+                if (resolved.value === null)
+                    decidable = false;
+                return resolved.value ?? value;
+            });
+            wanted.push([key, values]);
+        }
+        return decidable ? wanted : null;
+    }
+    /** The `W_UNRESOLVED_TOKEN` reporter of one step of `workflow`. */
+    reporter(workflow, stepName, diagnostics) {
+        const file = this.fileOf.get(workflow.name);
+        return (path, resolved) => {
+            for (const { token, reason } of resolved.unresolved) {
+                diagnostics.push({ code: exports.W_UNRESOLVED_TOKEN, severity: 'warning', file, path, message: `token '${token}' of ${stepName} has no value: ${reason}` });
+            }
+        };
+    }
+    /**
+     * Comparator of the iteration order over `type` (`spec-017` §1.3): ascending by the `{n}` token of the
+     * type's `id_pattern` when it has one — an id that does not match the pattern after every one that
+     * does — else byte-wise ascending `id`.
+     */
+    iterationOrder(type) {
+        const pattern = this.snapshot.memoryYaml.types[type].id_pattern;
+        const numeric = pattern !== undefined && [...pattern.matchAll(TOKEN_RE)].some((match) => (0, validation_1.isNumericToken)(match[1]));
+        const byId = (a, b) => compareText(a.id, b.id);
+        if (!numeric)
+            return byId;
+        const re = new RegExp(`^${(0, validation_1.patternToSource)(pattern, { captureNumeric: true })}$`);
+        const n = (element) => {
+            const match = re.exec(element.id);
+            return match === null ? Number.POSITIVE_INFINITY : Number(match[1]);
+        };
+        return (a, b) => {
+            const [x, y] = [n(a), n(b)];
+            return x === y ? byId(a, b) : x < y ? -1 : 1;
+        };
+    }
+    /**
+     * An `iterate_over` phase (§4.6): the sub once per candidate, in iteration order. Over a Memory type the
+     * `status` key of `where` is the entry filter and the other keys the scope filter; archived elements are
+     * never candidates (§4.11). Over a collection every entry matching `where` is a candidate. A candidate is
+     * complete when the sub is, entered when one of its phases is complete other than vacuously, eligible
+     * when it matches the entry filter, otherwise ignored. A `where` token with no value leaves the phase a
+     * single unexpanded step, reported with the token.
+     */
+    iterate(instanceId, startCommit, workflow, p, frames, exit, trail, scope, reentries) {
+        const phase = workflow.phases[p];
+        const over = phase.iterate_over;
+        const sub = this.byName.get(phase.include);
+        const whereDiagnostics = [];
+        const wanted = this.wanted(phase, p, frames, this.reporter(workflow, `${workflow.name}.${phase.name}`, whereDiagnostics));
+        if (wanted === null) {
+            const leaf = this.leaf(instanceId, startCommit, workflow, p, frames, exit, trail, scope, reentries);
+            return { complete: false, vacuous: false, liveQuery: true, frontier: [leaf.step], diagnostics: [...whereDiagnostics, ...leaf.diagnostics], late: [], closed: { late: [], count: 0 } };
+        }
+        // Each candidate: the frame it adds, the state its sub starts from, whether it passes the entry filter.
+        const candidates = [];
+        let label = over;
+        let entries = this.snapshot.collections?.get(over) ?? [];
+        if (over.startsWith(ELEMENT_COLLECTION)) {
+            const read = elementCollection(over, frames);
+            if ('reason' in read) {
+                // Undecided, like a `where` token with no value: one unexpanded step, reported.
+                whereDiagnostics.push({ code: exports.W_UNRESOLVED_TOKEN, severity: 'warning', file: this.fileOf.get(workflow.name), path: `phases[${p}].iterate_over`, message: read.reason });
+                const leaf = this.leaf(instanceId, startCommit, workflow, p, frames, exit, trail, scope, reentries);
+                return { complete: false, vacuous: false, liveQuery: true, frontier: [leaf.step], diagnostics: [...whereDiagnostics, ...leaf.diagnostics], late: [], closed: { late: [], count: 0 } };
+            }
+            label = read.label;
+            entries = read.entries;
+        }
+        if (COLLECTION_REF_RE.test(over)) {
+            for (const item of entries) {
+                // Every key exists: the registry refuses a collection with a key problem (`E_BINDING_COLLECTION_KEY`,
+                // `E_WORKFLOW_COLLECTION_UNRESOLVED`).
+                const key = (0, bindings_1.collectionEntryKey)(item);
+                const fields = typeof item === 'object' && item !== null ? item : {};
+                if (!wanted.every(([field, values]) => matches(fields[field], values)))
+                    continue;
+                candidates.push({ frame: { kind: 'item', collection: label, key, entry: item }, start: { boundType: null, state: null, instance: false }, entry: true, ref: null });
+            }
+        }
+        else {
+            const status = wanted.find(([key]) => key === 'status')?.[1];
+            const scopeFilter = wanted.filter(([key]) => key !== 'status');
+            const start = { boundType: sub.element ?? over, state: (0, workflow_exit_state_1.iterationStartState)(this.snapshot.memoryYaml, over, phase.where), instance: false };
+            this.elements
+                .filter((element) => element.type === over && !(0, state_machine_1.isArchivedStatus)(element.status) && scopeFilter.every(([key, values]) => matches(element.frontmatter[key], values)))
+                .sort(this.iterationOrder(over))
+                .forEach((element) => {
+                candidates.push({
+                    frame: { kind: 'element', type: over, element, pending: false },
+                    start,
+                    entry: status === undefined || status.includes(element.status),
+                    ref: refOf(element),
+                });
+            });
+        }
+        const counts = { eligible: 0, entered: 0, complete: 0 };
+        const frontier = [];
+        const diagnostics = [];
+        const late = [];
+        const completeLate = [];
+        const open = [];
+        let openCount = 0;
+        for (const candidate of candidates) {
+            // No cutoff is handed to an iteration: each iterated element has its own re-entries, which its sub's
+            // run finds (§4.8; approver ruling 2026-10-09).
+            const result = this.run(instanceId, startCommit, sub, [...frames, candidate.frame], candidate.start, trail);
+            if (result.complete) {
+                counts.complete += 1;
+                completeLate.push(...result.late);
+                continue;
+            }
+            if (result.progressed)
+                counts.entered += 1;
+            else if (candidate.entry)
+                counts.eligible += 1;
+            else
+                continue;
+            openCount += 1;
+            if (candidate.ref !== null)
+                open.push(candidate.ref);
+            frontier.push(...result.frontier);
+            diagnostics.push(...result.diagnostics);
+            late.push(...result.late);
+        }
+        const counted = counts.eligible + counts.entered + counts.complete;
+        return {
+            complete: openCount === 0,
+            vacuous: counted === 0,
+            liveQuery: true,
+            frontier,
+            diagnostics,
+            iterations: { ...counts, late: 0, ...(counted === 0 ? { note: exports.NO_ITERATION_NOTE } : {}) },
+            late: [...completeLate, ...late],
+            closed: { late: [...completeLate, ...open], count: openCount },
+        };
+    }
+    /** Evaluate one phase as a leaf step: its evidence, its `produces`, its unresolved tokens, what its selection matches. */
+    leaf(instanceId, startCommit, workflow, p, frames, exit, trail, scope, reentries) {
+        const phase = workflow.phases[p];
+        const stepName = `${workflow.name}.${phase.name}`;
+        const key = scope === null ? stepName : `${stepName}@${scopeKey(scope)}`;
+        const diagnostics = [];
+        const report = this.reporter(workflow, stepName, diagnostics);
+        const last = frames[frames.length - 1];
+        const frame = last?.kind === 'element' ? last : undefined;
+        const kinds = [];
+        const missing = [];
+        let selected = [];
+        // An `iterate_over` phase whose `where` cannot be resolved stays one unexpanded step (§4.6).
+        if (phase.iterate_over !== undefined) {
+            kinds.push('include');
+            missing.push('include');
+        }
+        // state — the bound element at or after the phase's exit state (§4.4), set by a commit newer than every
+        // re-entry that reaches this phase (§4.8).
+        if (declaresState(phase, exit.boundType)) {
+            kinds.push('state');
+            const element = frame?.element ?? null;
+            const satisfied = element !== null &&
+                exit.exit !== null &&
+                atOrAfter((0, state_machine_1.resolveStateMachine)(this.snapshot.memoryYaml, element.type), element.status, exit.exit) &&
+                this.newerThan(this.stateCommit(element), reentries);
+            if (!satisfied)
+                missing.push('state');
+        }
+        // What the step created (§4.8 linkage). A self-bound instance's steps had no scope before its element
+        // existed, so a linkage written then names the unscoped key.
+        const created = this.createdBy(instanceId, startCommit, frame?.selfBound ? [key, stepName] : [key]);
+        // produces — every string entry, resolved, names a committed path; implicit owners are shown only. A
+        // `{ type: T, path }` entry resolves against each element of `T` the step created and belongs to `created`.
+        const produces = [];
+        let producesEvidence = false;
+        let producesMissing = false;
+        let createdPathsMissing = false;
+        (phase.produces ?? []).forEach((entry, k) => {
+            if (typeof entry !== 'string') {
+                const owned = created.filter((element) => element.type === entry.type);
+                const resolved = [];
+                for (const element of owned) {
+                    const result = resolveTokens(entry.path, [...frames, { kind: 'element', type: entry.type, element, pending: false }]);
+                    report(`phases[${p}].produces[${k}].path`, result);
+                    if (result.value !== null)
+                        resolved.push(result.value);
+                }
+                const exists = owned.length > 0 && resolved.length === owned.length && resolved.every((path) => this.exists(path));
+                if (!exists)
+                    createdPathsMissing = true;
+                produces.push({ pattern: entry.path, owner: entry.type, resolved, exists, evidence: false });
+                return;
+            }
+            const resolved = resolveTokens(entry, frames);
+            report(`phases[${p}].produces[${k}]`, resolved);
+            const implicit = (0, workflow_diagnostics_1.isImplicitOwnerProduces)(workflow, p, entry);
+            const exists = resolved.value !== null && this.exists(resolved.value);
+            produces.push({
+                pattern: entry,
+                owner: implicit ? null : (frame?.type ?? null),
+                resolved: resolved.value === null ? [] : [resolved.value],
+                exists,
+                evidence: !implicit,
+            });
+            if (implicit)
+                return;
+            producesEvidence = true;
+            if (!exists)
+                producesMissing = true;
+        });
+        // created — for each type the phase adds, the step created at least one element, each at or after the
+        // state the phase leaves it in (§4.4), with each `{ type, path }` entry committed for it (§4.3). A step
+        // that created nothing leaves the kind to its other evidence, or to a record (below).
+        if ((phase.actions ?? []).some((action) => (0, bindings_1.tokenName)(action) === 'memory.add')) {
+            kinds.push('created');
+            if (created.length > 0 && (createdPathsMissing || !this.createdReachTargets(exit, created)))
+                missing.push('created');
+        }
+        if (producesEvidence) {
+            kinds.push('produces');
+            if (producesMissing)
+                missing.push('produces');
+        }
+        // selection — no Memory document at HEAD matches the phase's `where`; an archived one never does (§4.11).
+        if (phase.where !== undefined && phase.iterate_over === undefined) {
+            kinds.push('selection');
+            const wanted = this.wanted(phase, p, frames, report);
+            if (wanted !== null) {
+                selected = this.elements
+                    .filter((element) => !(0, state_machine_1.isArchivedStatus)(element.status) && wanted.every(([field, values]) => matches(element.frontmatter[field], values)))
+                    .map(refOf);
+            }
+            if (wanted === null || selected.length > 0)
+                missing.push('selection');
+        }
+        // awaits — evaluated from v1.0 (P4.12); the step completes by a record (§5.4).
+        if (phase.awaits !== undefined)
+            kinds.push('awaits');
+        // record — a checkpoint, an `awaits` (always, §4.3 `awaits` row, §5.4), a `created` step that created nothing
+        // and has no other evidence (§4.3), or an approval whose phase holds no gate: `workflow finalize` records it (§5.1).
+        const approvalRecord = phase.approval !== undefined && exit.held.length === 0;
+        const recordNeeded = phase.awaits !== undefined || approvalRecord || (created.length === 0 && !kinds.some((kind) => kind !== 'created'));
+        if (recordNeeded) {
+            kinds.push('record');
+            if (!this.hasRecord(instanceId, startCommit, stepName, scope, frame?.selfBound === true, reentries))
+                missing.push('record');
+        }
+        const actions = this.actionsOf(instanceId, startCommit, workflow, p, frames, exit, scope, created, selected, report);
+        const reentry = newest(reentries);
+        return {
+            step: {
+                key,
+                instance: instanceId,
+                trail,
+                workflow: workflow.name,
+                phase: phase.name,
+                scope,
+                role: phase.role ?? null,
+                optional: phase.optional,
+                produces,
+                created: created.map(refOf),
+                evidence: { kinds, missing, finalizable: missing.length === 1 && missing[0] === 'record' },
+                reentered: reentries.length > 0,
+                reentryCommit: reentry?.commit ?? null,
+                reentryFallback: reentry?.fallback ?? null,
+                approval: phase.approval === undefined ? null : { elements: awaitingElements(actions, exit), recordNeeded: approvalRecord },
+                actions,
+            },
+            diagnostics,
+            selected,
+        };
+    }
+    /**
+     * The actions of phase `p`, resolved (`spec-017` §4.1, §4.2; task-216): each token's text with its `{…}`
+     * substituted against `frames`, the tokens with no value (reported `W_UNRESOLVED_TOKEN` at
+     * `phases[p].actions[k]`), and what it acts on — the targets of §4.2's table, read at `HEAD`. A `{T.<field>}`
+     * whose `T` the phase's selection selects and no enclosing scope binds resolves per selected element when
+     * the action runs (§4.1), so it is kept as written and is not unresolved.
+     */
+    actionsOf(instanceId, startCommit, workflow, p, frames, exit, scope, created, selected, report) {
+        const phase = workflow.phases[p];
+        const selectedTypes = phase.where !== undefined && phase.iterate_over === undefined ? asStrings(phase.where['type']) : [];
+        const last = frames[frames.length - 1];
+        const bound = last?.kind === 'element' ? last.element : null;
+        const sorted = (elements) => [...elements].sort(compareRefs);
+        let addedType = null;
+        return (phase.actions ?? []).map((token, a) => {
+            const resolved = resolveTokens(token, frames);
+            const unresolved = resolved.unresolved.filter(({ token: name, reason }) => !(reason === 'no element in scope' && selectedTypes.includes(name.slice(1, -1).split('.')[0])));
+            report(`phases[${p}].actions[${a}]`, { ...resolved, unresolved });
+            // Each token with a value substituted; a pending or unresolved one (no value) kept as written.
+            const text = token.replace(TOKEN_RE, (whole) => resolveTokens(whole, frames).value ?? whole);
+            // The bound element's state before this action: the static state (§4.4) once an earlier action of the phase
+            // moved it; until then its status at `HEAD`, since the static start of an instance is its type's first state.
+            // `actionStates` holds one entry per action (`workflow-exit-state.ts`).
+            const statics = exit.actionStates;
+            const boundFrom = bound !== null && statics[a] === statics[0] ? bound.status : statics[a];
+            const base = { token, text, unresolved: unresolved.map((entry) => entry.token), boundFrom };
+            const target = this.actionTarget(instanceId, startCommit, workflow, p, frames, exit, scope, created, selected, token, boundFrom, addedType);
+            if ((0, bindings_1.tokenName)(token) === 'memory.add')
+                addedType = (0, bindings_1.memoryAddType)(token);
+            return { ...base, ...target, targets: sorted(target.targets) };
+        });
+    }
+    /**
+     * What one action of phase `p` acts on (`spec-017` §4.2's table): `created` after (or at) a `memory.add` of
+     * the phase, else the phase's selection, else the bound element, for the untyped verbs; for `<T>.set_state`
+     * the bound element of `T`, else the elements of `T` an earlier step of the pass created (`run`), else the
+     * selection of `T`; for `<T>.sync_state(for_each: <S>.<field>)` the elements of `T` that field of the
+     * nearest `S` names; otherwise nothing.
+     */
+    actionTarget(instanceId, startCommit, workflow, p, frames, exit, scope, created, selected, token, boundFrom, addedType) {
+        const phase = workflow.phases[p];
+        const name = (0, bindings_1.tokenName)(token);
+        const last = frames[frames.length - 1];
+        const frame = last?.kind === 'element' ? last : undefined;
+        const boundRefs = frame?.element ? [refOf(frame.element)] : [];
+        const ofType = (elements, type) => elements.filter((element) => element.type === type).map(refOf);
+        const none = { target: 'none', targetType: null, targets: [] };
+        if (name === 'memory.add') {
+            const type = (0, bindings_1.memoryAddType)(token);
+            return { target: 'created', targetType: type, targets: ofType(created, type) };
+        }
+        if (UNTYPED_TARGET_VERBS.includes(name)) {
+            if (addedType !== null)
+                return { target: 'created', targetType: addedType, targets: ofType(created, addedType) };
+            if (phase.where !== undefined && phase.iterate_over === undefined)
+                return { target: 'selection', targetType: null, targets: selected };
+            return frame === undefined ? none : { target: 'bound', targetType: frame.type, targets: boundRefs };
+        }
+        const typed = (0, bindings_1.typedStateType)(token);
+        if (typed === null)
+            return none;
+        if (name.endsWith('.set_state')) {
+            if (frame?.type === typed)
+                return { target: 'bound', targetType: typed, targets: boundRefs };
+            if (exit.run.some((element) => element.type === typed)) {
+                // The elements of `T` an earlier step of the same pass created (§4.2): the earlier phases' keys on this scope.
+                const suffix = scope === null ? '' : `@${scopeKey(scope)}`;
+                const earlier = workflow.phases.slice(0, p).flatMap(({ name: earlierName }) => {
+                    const stepName = `${workflow.name}.${earlierName}`;
+                    return frame?.selfBound ? [stepName + suffix, stepName] : [stepName + suffix];
+                });
+                return { target: 'run', targetType: typed, targets: ofType(this.createdBy(instanceId, startCommit, earlier), typed) };
+            }
+            const selection = phase.where !== undefined && phase.iterate_over === undefined && asStrings(phase.where['type']).includes(typed);
+            return { target: selection ? 'selection' : 'none', targetType: typed, targets: selection ? selected.filter((element) => element.type === typed) : [] };
+        }
+        // `<T>.sync_state(for_each: <S>.<field>)`: the elements of `T` the field of the nearest `S` names (§4.2).
+        const named = /for_each\s*:\s*["']?([a-z][a-z0-9-]*)\.([A-Za-z0-9_-]+)/.exec(token);
+        if (named === null)
+            return { target: 'run', targetType: typed, targets: [] };
+        const sourceType = named[1];
+        const sourceFrame = [...frames].reverse().find((candidate) => candidate.kind === 'element' && candidate.type === sourceType);
+        const source = sourceFrame?.element ?? null;
+        const ids = asStrings(source?.frontmatter[named[2]]);
+        const targets = ids.map((id) => this.find(typed, id)).filter((element) => element !== null);
+        const state = sourceFrame === frame ? boundFrom : (source?.status ?? null);
+        const peers = targets.map((target) => ({
+            id: target.id,
+            sources: this.elements
+                .filter((other) => other.type === sourceType && other.id !== source?.id && !(0, state_machine_1.isArchivedStatus)(other.status) && asStrings(other.frontmatter[named[2]]).includes(target.id))
+                .map(refOf)
+                .sort(compareRefs),
+        }));
+        return { target: 'run', targetType: typed, targets: targets.map(refOf), source: { type: sourceType, state, peers } };
+    }
+    /**
+     * Whether, for each type the phase adds (`exit.created`, its first `memory.add` of that type), the step
+     * created an element of it and each such element is at or after the state the phase leaves it in (§4.3,
+     * §4.4). An undetermined target state is never reached.
+     */
+    createdReachTargets(exit, created) {
+        const targets = new Map();
+        for (const added of exit.created)
+            if (!targets.has(added.type))
+                targets.set(added.type, added.state);
+        for (const [type, target] of targets) {
+            const owned = created.filter((element) => element.type === type);
+            if (owned.length === 0 || target === null)
+                return false;
+            const machine = (0, state_machine_1.resolveStateMachine)(this.snapshot.memoryYaml, type);
+            if (!owned.every((element) => atOrAfter(machine, element.status, target)))
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Whether the instance's walk holds a record of step `stepName` on `scope` (§4.8 records) — its
+     * `WingFoil-Element` or `WingFoil-Item` — newer than every re-entry that reaches the step (a descendant
+     * of each). A self-bound scope also accepts a record with no element, written before the element existed.
+     */
+    hasRecord(instanceId, startCommit, stepName, scope, selfBound, reentries) {
+        const element = scope !== null && 'element' in scope ? scopeKey(scope) : null;
+        const item = scope !== null && 'item' in scope ? scopeKey(scope) : null;
+        return this.history(startCommit).records.some((record) => record.phase === stepName &&
+            record.instance === instanceId &&
+            (record.element === element || (selfBound && record.element === null)) &&
+            record.item === item &&
+            this.newerThan(record.commit, reentries));
+    }
+    /** The frames an instance of `workflow` starts with, its bound element and its context (§3.4, §3.5). */
+    bind(workflow, plan, startCommit) {
+        const id = scalarText(plan.frontmatter['element']);
+        if (workflow.element !== undefined) {
+            const element = id === null ? null : this.find(workflow.element, id);
+            return {
+                frames: [{ kind: 'element', type: workflow.element, element, pending: false }],
+                start: { boundType: workflow.element, state: this.firstState(workflow.element), instance: true },
+                element,
+                context: null,
+            };
+        }
+        const contextElement = id === null ? null : this.findAny(id);
+        const context = contextElement === null ? null : refOf(contextElement);
+        const creating = (0, workflow_diagnostics_1.creatingPhaseIndex)(workflow);
+        // The creating phase is the one holding the first `memory.add`, so it has actions; a `memory.add` with
+        // no `type:` names no type, and the instance then has no frame.
+        const type = creating === -1 ? null : (workflow.phases[creating].actions.map(bindings_1.memoryAddType).find((t) => t !== null) ?? null);
+        const start = { boundType: null, state: null, instance: true };
+        if (type === null)
+            return { frames: [], start, element: null, context };
+        // Self-creating (§3.4): bound to the element of `type` its creating step created with the oldest add
+        // commit (ties by ascending id); until then unbound, its tokens pending.
+        const step = `${workflow.name}.${workflow.phases[creating].name}`;
+        const bound = this.history(startCommit)
+            .links.filter((link) => link.instance === plan.id && link.step === step && link.type === type)
+            .sort((a, b) => b.position - a.position || compareText(a.id, b.id))
+            .map((link) => this.find(link.type, link.id))
+            .find((element) => element !== null) ?? null;
+        if (bound === null)
+            return { frames: [{ kind: 'element', type, element: null, pending: true }], start, element: null, context };
+        return { frames: [{ kind: 'element', type, element: bound, pending: false, selfBound: true }], start, element: bound, context };
+    }
+}
+/** A phase's progress entry, with `vacuous` and `iterations` only where they apply. */
+function progress(phase, state, vacuous, iterations) {
+    return { phase, state, ...(vacuous ? { vacuous: true } : {}), ...(iterations !== undefined ? { iterations } : {}) };
+}
+// --- The deduction -----------------------------------------------------------------------------------
+/**
+ * Deduce every open workflow instance at the snapshot's commit (`spec-017` §3–§4): its bound element,
+ * its top-level phase progress and its frontier, plus the ordered diagnostics of §1.3 — the registry's,
+ * then `W_UNCOMMITTED_INPUTS`, then `W_MEMORY_*` by path, then `W_INSTANCE_WORKFLOW_UNKNOWN` in
+ * instance order, then the step-attached `W_UNRESOLVED_TOKEN` in frontier order. Never throws on a
+ * Memory document it cannot use: it leaves the document out and reports it (§1.4).
+ */
+function deduceWorkflowState(snapshot) {
+    const { elements, diagnostics: memoryDiagnostics } = readElements(snapshot);
+    const deducer = new Deducer(snapshot, elements);
+    const open = deducer
+        .plans()
+        .filter((plan) => exports.OPEN_PLAN_STATUSES.includes(plan.status) && scalarText(plan.frontmatter['parent']) === null)
+        .map((plan) => {
+        const start = snapshot.starts.get(plan.path);
+        return { plan, workflowName: scalarText(plan.frontmatter['workflow']) ?? '', start, position: start?.position ?? Number.MAX_SAFE_INTEGER };
+    })
+        .filter(({ workflowName }) => {
+        const workflow = deducer.workflow(workflowName);
+        return workflow === undefined || (0, schema_1.workflowFacts)(workflow).startable;
+    })
+        .sort((a, b) => a.position - b.position || compareText(a.plan.id, b.plan.id));
+    const unknownDiagnostics = [];
+    const stepDiagnostics = [];
+    const instances = open.map(({ plan, workflowName, start }, index) => {
+        const workflow = deducer.workflow(workflowName);
+        const startCommit = start?.commit ?? '';
+        const base = {
+            id: plan.id,
+            workflow: workflowName,
+            created: deducer.createdBy(plan.id, startCommit, null).map(refOf),
+            planStatus: plan.status,
+            startCommit,
+            active: index === 0,
+            abandoned: false,
+        };
+        if (workflow === undefined) {
+            unknownDiagnostics.push({
+                code: exports.W_INSTANCE_WORKFLOW_UNKNOWN,
+                severity: 'warning',
+                file: plan.path,
+                path: 'workflow',
+                message: `open plan ${plan.id} names workflow '${workflowName}', which the registry does not load`,
+            });
+            return { instance: { ...base, element: null, context: null }, complete: false, phases: [], frontier: [], late: [] };
+        }
+        const bound = deducer.bind(workflow, plan, startCommit);
+        const element = bound.element === null ? null : refOf(bound.element);
+        // An archived bound element abandons the instance: nothing is deduced for it (§4.11).
+        if (bound.element !== null && (0, state_machine_1.isArchivedStatus)(bound.element.status)) {
+            return { instance: { ...base, element, context: bound.context, abandoned: true }, complete: false, phases: [], frontier: [], late: [] };
+        }
+        const result = deducer.run(plan.id, startCommit, workflow, bound.frames, bound.start, []);
+        stepDiagnostics.push(...result.diagnostics);
+        const late = new Map(result.late.map((ref) => [`${ref.type}:${ref.id}`, ref]));
+        return {
+            instance: { ...base, element, context: bound.context },
+            complete: result.complete,
+            phases: result.phases,
+            frontier: result.frontier,
+            late: [...late.values()].sort(compareRefs),
+        };
+    });
+    const uncommitted = snapshot.dirty.map(uncommittedInputDiagnostic);
+    // The elements waiting at a gate (§5.1): `status` lists those no pending approval carries. Every element's type is
+    // declared in `memory.yaml` (`readElements` leaves the others out), so the machine resolves. A gate that is also a
+    // `waiting` state is left out: its forward edge is verb-less, so no approver acts on it — a workflow action advances
+    // it (dl-123; `memory approve` refuses it).
+    const gated = elements
+        .filter((element) => {
+        const machine = (0, state_machine_1.resolveStateMachine)(snapshot.memoryYaml, element.type);
+        return Object.prototype.hasOwnProperty.call(machine.gates ?? {}, element.status) && !(machine.waiting ?? []).includes(element.status);
+    })
+        .map(refOf)
+        .sort(compareRefs);
+    return {
+        baseline: { rev: 'HEAD', commit: snapshot.commit },
+        active: instances[0]?.instance.id ?? null,
+        instances,
+        diagnostics: [...snapshot.registryDiagnostics, ...uncommitted, ...memoryDiagnostics, ...unknownDiagnostics, ...stepDiagnostics],
+        gated,
+    };
+}
+/**
+ * The open instance `ref` names (`spec-017` §3.3): a workflow name selects its most recently started
+ * open instance, an instance id that instance; no `ref` selects the active instance. `null` when none.
+ */
+function resolveInstanceRef(deduction, ref) {
+    if (ref === undefined)
+        return deduction.instances[0] ?? null;
+    return deduction.instances.find((entry) => entry.instance.workflow === ref) ?? deduction.instances.find((entry) => entry.instance.id === ref) ?? null;
+}
+//# sourceMappingURL=deduce.js.map