wingfoil 0.2.2 → 0.3.0

package/dist/core/workflow-exit-state.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.machineStates = machineStates;
+exports.iterationStartState = iterationStartState;
+exports.workflowExitStates = workflowExitStates;
+const state_machine_1 = require("../memory/state-machine");
+const bindings_1 = require("../workflow/bindings");
+const schema_1 = require("../workflow/schema");
+/** The machine of `type`, or `null` when `memory.yaml` does not register it (that is a separate diagnostic). */
+function machineOf(memoryYaml, type) {
+    return Object.prototype.hasOwnProperty.call(memoryYaml.types, type) ? (0, state_machine_1.resolveStateMachine)(memoryYaml, type) : null;
+}
+/** Every state an element of a type can be in: its `sequence`, its reject and return targets, and `deprecated`. */
+function machineStates(machine) {
+    const states = new Set(machine.sequence);
+    for (const gate of Object.values(machine.gates ?? {}))
+        states.add(gate.reject);
+    for (const target of Object.values(machine.returns ?? {}))
+        states.add(target);
+    states.add(state_machine_1.DEPRECATED_STATE);
+    return states;
+}
+/**
+ * The state an element enters a workflow run under `iterate_over` in (`spec-017` §4.4): the
+ * lowest-`sequence` value of the governing `where.status`, otherwise the type's first state. `null`
+ * when `memory.yaml` does not register `type`.
+ */
+function iterationStartState(memoryYaml, type, where) {
+    const machine = machineOf(memoryYaml, type);
+    if (!machine)
+        return null;
+    const raw = where?.['status'];
+    const statuses = (Array.isArray(raw) ? raw : raw === undefined ? [] : [raw]).map(String);
+    const positions = statuses.map((status) => machine.sequence.indexOf(status)).filter((index) => index !== -1);
+    return machine.sequence[positions.length > 0 ? Math.min(...positions) : 0]; // a sequence is never empty (spec-001)
+}
+/** The first state of `type`, or `null` for an unregistered type. */
+function firstState(memoryYaml, type) {
+    return machineOf(memoryYaml, type)?.sequence[0] ?? null;
+}
+/** An untyped Memory verb token's transition, or `null` for any other token. */
+const UNTYPED_VERBS = {
+    'memory.submit': 'submit',
+    'memory.approve': 'approve',
+    'memory.reject': 'reject',
+    'memory.deprecate': 'deprecate',
+};
+/** The `s` of `….set_state(s)`, unquoted, or `null`. */
+function setStateArgument(token) {
+    const match = /\(\s*["']?([^"'()\s]+)["']?\s*\)/.exec(token);
+    return match ? match[1] : null;
+}
+/** A selection's types and statuses, each a list (`spec-003` § "Selections"). */
+function asList(value) {
+    if (value === undefined)
+        return [];
+    return (Array.isArray(value) ? value : [value]).map(String);
+}
+/**
+ * The exit states of every phase of `workflow` (`spec-017` §4.4), in declared order.
+ *
+ * A plain `include:` phase runs the included workflow on the same element (§4.5) — found by name in
+ * `workflows` — and leaves the element in the state the included workflow's last phase leaves it in.
+ * An `iterate_over` phase runs its sub on other elements: the bound element's state is unchanged.
+ *
+ * @param workflow - The workflow whose phases are computed.
+ * @param memoryYaml - The `memory.yaml` the machines come from.
+ * @param start - The bound element's type and state at the first phase.
+ * @param workflows - The registry, by name, a plain `include:` is resolved in (default: none).
+ */
+function workflowExitStates(workflow, memoryYaml, start, workflows = new Map()) {
+    return compute(workflow, memoryYaml, start, workflows, new Set([workflow.name]));
+}
+function compute(workflow, memoryYaml, start, workflows, visiting) {
+    const creating = start.instance && start.boundType === null && workflow.element === undefined && (0, schema_1.workflowFacts)(workflow).startable
+        ? workflow.phases.findIndex((phase) => (phase.actions ?? []).some((action) => (0, bindings_1.tokenName)(action) === 'memory.add'))
+        : -1;
+    let bound = start.boundType === null ? null : { type: start.boundType, action: -1, state: start.state };
+    // The elements created by earlier phases of this pass, the targets of a typed `<T>.set_state`.
+    const earlier = [];
+    const out = [];
+    workflow.phases.forEach((phase, p) => {
+        const entry = bound?.state ?? null;
+        const held = [];
+        const created = [];
+        const run = new Set();
+        let undetermined = null;
+        const hold = (type, gate, reject) => {
+            if (!held.some((h) => h.type === type && h.gate === gate))
+                held.push({ type, gate, reject });
+        };
+        /** Apply one transition to `target`, recording the first refusal and the gates it holds. */
+        const apply = (target, action, op) => {
+            const machine = machineOf(memoryYaml, target.type);
+            if (!machine)
+                return; // an unregistered type is E_WORKFLOW_ELEMENT_TYPE_UNKNOWN's, not this
+            const from = target.state;
+            const refuse = (reason) => {
+                undetermined ??= { action, type: target.type, from, reason };
+                target.state = null;
+            };
+            if (typeof op === 'object') {
+                const to = op.setState;
+                if (!machineStates(machine).has(to))
+                    return refuse(`'${to}' is not a state of ${target.type}`);
+                if (from !== null) {
+                    const fromIndex = machine.sequence.indexOf(from);
+                    const toIndex = machine.sequence.indexOf(to);
+                    if (fromIndex !== -1 && toIndex !== -1 && toIndex <= fromIndex) {
+                        return refuse(`'${to}' does not lie after '${from}' in ${target.type}'s sequence`);
+                    }
+                    const gate = machine.gates?.[from];
+                    if (gate && fromIndex !== -1 && machine.sequence[fromIndex + 1] === to)
+                        hold(target.type, from, gate.reject);
+                }
+                target.state = to;
+                return;
+            }
+            if (from === null) {
+                if (op === 'deprecate')
+                    target.state = state_machine_1.DEPRECATED_STATE;
+                else
+                    refuse('the state it starts from is undetermined');
+                return;
+            }
+            let to;
+            try {
+                to = (0, state_machine_1.resolveTransitionTarget)(machine, from, op);
+            }
+            catch (error) {
+                // `resolveTransitionTarget` refuses only with an `E_INVALID_TRANSITION` ValidationError.
+                return refuse(error.issues[0].message);
+            }
+            const leftGate = machine.gates?.[from];
+            if ((op === 'approve' || op === 'reject') && leftGate)
+                hold(target.type, from, leftGate.reject);
+            const enteredGate = machine.gates?.[to];
+            if (op === 'submit' && enteredGate)
+                hold(target.type, to, enteredGate.reject);
+            target.state = to;
+        };
+        if (phase.include !== undefined) {
+            const sub = workflows.get(phase.include);
+            if (phase.iterate_over === undefined && sub && !visiting.has(sub.name)) {
+                const subType = sub.element ?? bound?.type ?? null;
+                const sameElement = bound !== null && subType === bound.type;
+                const subStates = compute(sub, memoryYaml, { boundType: subType, state: sameElement ? bound.state : subType === null ? null : firstState(memoryYaml, subType), instance: false }, workflows, new Set([...visiting, sub.name]));
+                const last = subStates[subStates.length - 1];
+                if (sameElement && last)
+                    bound.state = last.exit;
+            }
+            out.push({ phase: phase.name, boundType: bound?.type ?? null, entry, exit: bound?.state ?? null, undetermined: null, created: [], run: [], held: [], actionStates: [] });
+            return;
+        }
+        const selection = phase.where !== undefined && phase.iterate_over === undefined;
+        let latest = null;
+        let actsOnSelection = false;
+        // `<T>.set_state(s)` on the selection (§4.2 last fallback): the `(T, s)` pairs, in action order.
+        const selectionSets = [];
+        const actionStates = [];
+        (phase.actions ?? []).forEach((action, a) => {
+            actionStates.push(bound?.state ?? null);
+            const name = (0, bindings_1.tokenName)(action);
+            if (name === 'memory.add') {
+                const type = (0, bindings_1.memoryAddType)(action);
+                if (type === null)
+                    return;
+                const element = { type, action: a, state: firstState(memoryYaml, type) };
+                created.push(element);
+                latest = element;
+                if (p === creating && bound === null)
+                    bound = element;
+                return;
+            }
+            const verb = UNTYPED_VERBS[name];
+            const untypedSet = name === 'element.set_state';
+            if (verb !== undefined || untypedSet) {
+                const op = untypedSet ? { setState: setStateArgument(action) ?? '' } : verb;
+                if (latest)
+                    apply(latest, a, op);
+                else if (selection)
+                    actsOnSelection = true;
+                else if (bound)
+                    apply(bound, a, op);
+                return;
+            }
+            const typed = /^([a-z][a-z0-9-]*)\.set_state$/.exec(name);
+            if (typed) {
+                const type = typed[1];
+                const op = { setState: setStateArgument(action) ?? '' };
+                if (bound && bound.type === type) {
+                    apply(bound, a, op);
+                    return;
+                }
+                const earlierOfType = earlier.filter((candidate) => candidate.type === type);
+                for (const element of earlierOfType) {
+                    apply(element, a, op);
+                    run.add(element);
+                }
+                if (earlierOfType.length === 0 && selection && asList(phase.where['type']).includes(type)) {
+                    selectionSets.push({ type, to: op.setState });
+                }
+            }
+        });
+        if (selection && actsOnSelection) {
+            const statuses = asList(phase.where['status']);
+            for (const type of asList(phase.where['type'])) {
+                const machine = machineOf(memoryYaml, type);
+                if (!machine)
+                    continue;
+                for (const status of statuses) {
+                    const gate = machine.gates?.[status];
+                    if (gate)
+                        hold(type, status, gate.reject);
+                }
+            }
+        }
+        for (const { type, to } of selectionSets) {
+            const machine = machineOf(memoryYaml, type);
+            if (!machine)
+                continue;
+            for (const status of asList(phase.where['status'])) {
+                const gate = machine.gates?.[status];
+                if (gate && machine.sequence[machine.sequence.indexOf(status) + 1] === to)
+                    hold(type, status, gate.reject);
+            }
+        }
+        earlier.push(...created.filter((element) => element !== bound));
+        out.push({
+            phase: phase.name,
+            boundType: bound?.type ?? null,
+            entry,
+            exit: bound?.state ?? null,
+            undetermined,
+            created: created.map((element) => ({ type: element.type, action: element.action, state: element.state })),
+            run: [...run].map((element) => ({ type: element.type, action: element.action, state: element.state })),
+            held,
+            actionStates,
+        });
+    });
+    return out;
+}
+//# sourceMappingURL=workflow-exit-state.js.map

package/dist/core/workflow-exit-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-exit-state.js","sourceRoot":"","sources":["../../src/core/workflow-exit-state.ts"],"names":[],"mappings":"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"}

package/dist/core/workflow-finalize.d.ts

@@ -0,0 +1,37 @@
+import { type Baseline, type DeducedStep, type Instance } from '../workflow/deduce';
+import { type CoreResult } from './types';
+import { type Step } from './workflow-next';
+/** The refusal when no `<ref>` is given and no instance is open (as `workflow end`'s, `spec-017` §10). */
+export declare const NO_ACTIVE_WORKFLOW_TO_FINALIZE = "no active workflow to finalize";
+/** `workflow finalize`'s payload (`spec-017` §8 `FinalizeResult`). */
+export interface FinalizeResult {
+    /** The commit the finalize gated on — `HEAD` before its record. */
+    readonly baseline: Baseline;
+    readonly instance: Instance;
+    /** The step the record completes, as `workflow next` reported it at the baseline. */
+    readonly finalized: Step;
+    /** The instance's next step after the record, deduced at the new `HEAD`; `null` when it has none. */
+    readonly next: Step | null;
+    /** The record's commit sha. */
+    readonly commit: string;
+}
+/** What the caller asked for: `<ref>`, `--step`, and the raw `--reason` (as `optionalReason` reads it). */
+export interface FinalizeRequest {
+    readonly ref?: string;
+    readonly step?: string;
+    readonly options?: Readonly<Record<string, string>>;
+}
+/** The phase-record trailers of `step` (`spec-003` § "Evidence"), in the order the spec lists them. */
+export declare function phaseRecordTrailers(step: Pick<DeducedStep, 'workflow' | 'phase' | 'instance' | 'scope'>): string[];
+/**
+ * `workflow finalize` at `HEAD` (`spec-017` §7.9). See the module comment for the record and the order of
+ * the refusals.
+ *
+ * @throws `UsageError` (exit 2) for an unrecordable `--reason`, or a missing one on an `approval:` phase.
+ * @throws `DiagnosticsError` (`VALIDATION`) when the registry at `HEAD` has a `spec-003` error;
+ *   `StorageError` when git cannot answer; `CommitFailure` when git refuses the commit.
+ */
+export declare function workflowFinalizeAtHead(root: string, request: FinalizeRequest): CoreResult<FinalizeResult>;
+/** `workflow finalize`'s `--format console` rendering (`spec-017` §8). Pure. */
+export declare function renderFinalizeConsole(result: FinalizeResult): string;
+//# sourceMappingURL=workflow-finalize.d.ts.map

package/dist/core/workflow-finalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-finalize.d.ts","sourceRoot":"","sources":["../../src/core/workflow-finalize.ts"],"names":[],"mappings":"AAoCA,OAAO,EAA2C,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAiB,MAAM,oBAAoB,CAAC;AAK5I,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAE3D,OAAO,EAA6E,KAAK,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAGvH,0GAA0G;AAC1G,eAAO,MAAM,8BAA8B,mCAAmC,CAAC;AAE/E,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,qGAAqG;IACrG,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAC3B,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,2GAA2G;AAC3G,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAOD,uGAAuG;AACvG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC,GAAG,MAAM,EAAE,CAElH;AA0BD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,UAAU,CAAC,cAAc,CAAC,CAiDzG;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAKpE"}

package/dist/core/workflow-finalize.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_ACTIVE_WORKFLOW_TO_FINALIZE = void 0;
+exports.phaseRecordTrailers = phaseRecordTrailers;
+exports.workflowFinalizeAtHead = workflowFinalizeAtHead;
+exports.renderFinalizeConsole = renderFinalizeConsole;
+/**
+ * `wingfoil workflow finalize [<ref>] [--step <key>] [--reason <text>]` (task-226; `spec-017` §7.9, §4.3
+ * `record`, §5.1, §5.4, §8 `FinalizeResult`, §10, §11; ruling R11; `dl-104` D1 (b)–(c); REQ-SEC-01,
+ * REQ-SEC-03, P1.7).
+ *
+ * Records a phase's completion where the phase has no Memory or file evidence to deduce it from: a
+ * checkpoint, an `awaits` (§5.4), a `created` step that created nothing, and an approval no element carries
+ * (§5.1). The record is **one commit with no file change** (`commitEmpty`, `src/storage/commit.ts`):
+ *
+ * ```
+ * workflow: finalize <instance-id> <key>
+ *
+ * Approver: <name> <<email>> (approver)      ← an `approval:` phase only
+ * Reason: <the dl-067 block>                 ← when `--reason` is given
+ *
+ * WingFoil-Phase: <workflow>.<phase> completed
+ * WingFoil-Instance: <instance-id>
+ * WingFoil-Element: <type>:<id>              ← or WingFoil-Item: <collection>#<key>; none when unscoped
+ * WingFoil-Version: <semver> (<sha>)
+ * ```
+ *
+ * The subject is outside the `wf(<type>)` grammar (`spec-003` verb table), so `memory history` never reads it
+ * as a Memory operation; the trailers are the phase record of `spec-003` § "Evidence", which the deduction
+ * reads with git's `%(trailers)` — from the **final** paragraph only, which is why they share it with the
+ * build signature (`CommitOptions.trailers`).
+ *
+ * **Baseline: `HEAD`, gating** (`spec-017` §1.1, §11): the deduction that names the frontier, and
+ * `dna.yaml` for approval authority, are read at `HEAD`; nothing is read from the working tree except the
+ * index, whose staged changes refuse the commit (`requireCleanIndex`, `dl-106`).
+ *
+ * **Refusal order**, every one before the commit: an unrecordable `--reason` (exit 2, before any read) →
+ * the git identity (REQ-SEC-01) → the instance → the step on the frontier → its evidence → on an
+ * `approval:` phase, a missing `--reason` (exit 2) and approver authority (REQ-SEC-03, the identity read
+ * once, `bug-149`) → a dirty index.
+ */
+const storage_1 = require("../storage");
+const deduce_1 = require("../workflow/deduce");
+const approval_authority_1 = require("./approval-authority");
+const git_identity_1 = require("./git-identity");
+const require_reason_1 = require("./require-reason");
+const types_1 = require("./types");
+const workflow_deduction_1 = require("./workflow-deduction");
+const workflow_next_1 = require("./workflow-next");
+const write_guard_1 = require("./write-guard");
+/** The refusal when no `<ref>` is given and no instance is open (as `workflow end`'s, `spec-017` §10). */
+exports.NO_ACTIVE_WORKFLOW_TO_FINALIZE = 'no active workflow to finalize';
+/** `<type>:<id>` or `<collection>#<key>`, as the record's trailer and the step key write a scope. */
+function scopeTrailer(scope) {
+    return 'item' in scope ? `WingFoil-Item: ${scope.item.collection}#${scope.item.key}` : `WingFoil-Element: ${scope.element.type}:${scope.element.id}`;
+}
+/** The phase-record trailers of `step` (`spec-003` § "Evidence"), in the order the spec lists them. */
+function phaseRecordTrailers(step) {
+    return [`WingFoil-Phase: ${step.workflow}.${step.phase} completed`, `WingFoil-Instance: ${step.instance}`, ...(step.scope === null ? [] : [scopeTrailer(step.scope)])];
+}
+/**
+ * The Memory type named in the authority refusal (`user not authorized to approve type '<type>'`): the
+ * step's scope element's type, else the instance's bound element's, else `plan` — the instance itself.
+ */
+function authorityType(step, instance) {
+    if (step.scope !== null && 'element' in step.scope)
+        return step.scope.element.type;
+    return instance.element?.type ?? 'plan';
+}
+/**
+ * Why `step` cannot be finalized: its phase completes from other evidence (`spec-017` §7.9, `dl-104` D1
+ * rationale). Names the missing kinds other than `record`, or — when none is missing — the kinds the phase
+ * declares other than `record`.
+ */
+function evidenceRefusal(step) {
+    const missing = step.evidence.missing.filter((kind) => kind !== 'record');
+    const kinds = missing.length > 0 ? missing : step.evidence.kinds.filter((kind) => kind !== 'record');
+    return (0, types_1.coreErr)({
+        code: 'CONFLICT',
+        message: `phase '${step.workflow}.${step.phase}' completes from its evidence: ${kinds.join(', ')}`,
+        details: { step: step.key, kinds: [...step.evidence.kinds], missing: [...step.evidence.missing] },
+    });
+}
+/**
+ * `workflow finalize` at `HEAD` (`spec-017` §7.9). See the module comment for the record and the order of
+ * the refusals.
+ *
+ * @throws `UsageError` (exit 2) for an unrecordable `--reason`, or a missing one on an `approval:` phase.
+ * @throws `DiagnosticsError` (`VALIDATION`) when the registry at `HEAD` has a `spec-003` error;
+ *   `StorageError` when git cannot answer; `CommitFailure` when git refuses the commit.
+ */
+function workflowFinalizeAtHead(root, request) {
+    const given = (0, require_reason_1.optionalReason)(request.options);
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
+    const snapshot = (0, workflow_deduction_1.readDeductionSnapshotAtHead)(root);
+    const deduction = (0, deduce_1.deduceWorkflowState)(snapshot);
+    const selected = (0, deduce_1.resolveInstanceRef)(deduction, request.ref);
+    if (selected === null) {
+        if (request.ref !== undefined)
+            return (0, workflow_next_1.unresolvedRef)({ workflows: snapshot.workflows, plans: (0, workflow_deduction_1.instancePlanIds)(snapshot.documents) }, request.ref);
+        return (0, types_1.coreErr)({ code: 'NOT_FOUND', message: exports.NO_ACTIVE_WORKFLOW_TO_FINALIZE });
+    }
+    const { instance, frontier } = selected;
+    if (frontier.length === 0)
+        return (0, types_1.coreErr)({ code: 'CONFLICT', message: (0, workflow_next_1.emptyFrontierMessage)(selected), details: { instance: instance.id } });
+    const step = request.step === undefined ? frontier[0] : frontier.find((candidate) => candidate.key === request.step);
+    if (step === undefined) {
+        return (0, types_1.coreErr)({
+            code: 'CONFLICT',
+            message: `step '${request.step}' is not on the frontier of ${instance.id}`,
+            details: { frontier: frontier.map((candidate) => candidate.key) },
+        });
+    }
+    if (!step.evidence.finalizable)
+        return evidenceRefusal(step);
+    // A frontier step's workflow and phase are loaded (deduction puts only loaded phases on a frontier).
+    const phase = snapshot.workflows.find((workflow) => workflow.name === step.workflow).phases.find((candidate) => candidate.name === step.phase);
+    const body = [];
+    if (phase.approval !== undefined) {
+        const reason = (0, require_reason_1.requireReason)(request.options);
+        const authorized = (0, approval_authority_1.requireApprovalAuthority)(root, authorityType(step, instance), identity.value);
+        if (!authorized.ok)
+            return authorized;
+        body.push(`Approver: ${identity.value.name} <${identity.value.email}> (${approval_authority_1.APPROVER_ROLE})`, `Reason: ${reason}`);
+    }
+    else if (given !== undefined) {
+        body.push(`Reason: ${given}`);
+    }
+    const subject = `workflow: finalize ${instance.id} ${step.key}`;
+    const clean = (0, write_guard_1.requireCleanIndex)(root, subject);
+    if (!clean.ok)
+        return clean;
+    const finalized = (0, workflow_next_1.buildStep)(step, (0, workflow_next_1.readNextInputs)(root, snapshot, deduction));
+    const message = body.length === 0 ? subject : `${subject}\n\n${body.join('\n')}`;
+    const sha = (0, storage_1.commitEmpty)(root, message, { author: identity.value, trailers: phaseRecordTrailers(step) });
+    const after = (0, workflow_deduction_1.readDeductionSnapshotAtHead)(root);
+    const deducedAfter = (0, deduce_1.deduceWorkflowState)(after);
+    const nextStep = deducedAfter.instances.find((entry) => entry.instance.id === instance.id)?.frontier[0];
+    const next = nextStep === undefined ? null : (0, workflow_next_1.buildStep)(nextStep, (0, workflow_next_1.readNextInputs)(root, after, deducedAfter));
+    return (0, types_1.coreOk)({ baseline: deduction.baseline, instance, finalized, next, commit: sha }, { sha, message });
+}
+/** `workflow finalize`'s `--format console` rendering (`spec-017` §8). Pure. */
+function renderFinalizeConsole(result) {
+    const lines = [`workflow: ${result.instance.workflow} (${result.instance.id})`, `finalized: ${result.finalized.key} (${result.commit})`];
+    if (result.next === null)
+        lines.push('no next step');
+    else
+        lines.push(...(0, workflow_next_1.stepLines)(result.next, 'next step'));
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=workflow-finalize.js.map

package/dist/core/workflow-finalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-finalize.js","sourceRoot":"","sources":["../../src/core/workflow-finalize.ts"],"names":[],"mappings":"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"}

package/dist/core/workflow-list-show.d.ts

@@ -0,0 +1,176 @@
+/**
+ * `wingfoil workflow list [--all]` and `wingfoil workflow show <ref>` (task-204; `spec-017` §7.5, §7.6, §8,
+ * §10; BDD P4.6, P4.7).
+ *
+ * **Baseline: `HEAD`, declared** (`spec-017` §1.1, approver ruling R15; `spec-006` §6 item 6; `spec-008`
+ * §11). Both commands answer from one snapshot of the repository as committed at `HEAD` —
+ * `readDeductionSnapshotAtHead` — and from the deduction computed on it (`deduceWorkflowState`), the one
+ * `workflow next` / `status` answer from, so a workflow "executable now" here is one a frontier step there
+ * enters. The working tree only explains: a deduction input that differs from `HEAD` is the warning
+ * `W_UNCOMMITTED_INPUTS` (§1.2), never the answer. `show`'s further reads — `workflows/bindings.yaml`,
+ * `roles.yaml` and the directive files — are made at the snapshot's commit, so one answer has one baseline.
+ *
+ * Both payloads carry the `baseline` and the deduction's ordered `diagnostics` (§1.3). A `spec-003` error
+ * refuses both: the snapshot reader throws `DiagnosticsError`, which the read-only operations map to
+ * `VALIDATION` with every diagnostic in `details` (exit `1`, §10).
+ *
+ * The MCP Resources `wingfoil://workflows` and `wingfoil://workflows/{name}` are not these operations: they
+ * keep their payload and their working-tree baseline in v0.3 (§9, `src/mcp/workflow-resource.ts`).
+ */
+import type { RolesYaml } from '../directives/schema';
+import type { MemoryYaml } from '../memory/schema';
+import type { Diagnostic } from '../validation';
+import { type BindingsYaml, type TokenBinding } from '../workflow/bindings';
+import { type Baseline, type Deduction, type EvidenceKind } from '../workflow/deduce';
+import { type Cadence, type PhaseMode, type Workflow } from '../workflow/schema';
+import { type DirectiveFile } from './loaders';
+import { type CoreResult } from './types';
+/** `ListResult.message` when `HEAD` holds no manifest (BDD P4.6 sc. 4; `spec-003` Layer 1). */
+export declare const NO_WORKFLOWS_DEFINED = "no workflows defined";
+/** The refusal of a `<ref>` that names no workflow (`spec-017` §10, BDD P4.7 sc. 3). */
+export declare const unknownWorkflowMessage: (name: string) => string;
+/** One entry of `workflow list` (`spec-017` §8 `ListResult`). */
+export interface ListEntry {
+    readonly name: string;
+    readonly startable: boolean;
+    readonly includable: boolean;
+    readonly description: string | null;
+    /** Startable, or the sub a phase on an open instance's frontier includes (§7.5). */
+    readonly executableNow: boolean;
+}
+/** `workflow list`'s payload (`spec-017` §8). */
+export interface ListResult {
+    readonly baseline: Baseline;
+    readonly workflows: readonly ListEntry[];
+    /** `no workflows defined` when `HEAD` holds no manifest; absent otherwise. */
+    readonly message?: string;
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** An action or check token with its binding (`spec-017` §6.1); a check is never evaluated in v0.3. */
+export interface TokenView {
+    readonly token: string;
+    readonly binding: TokenBinding;
+}
+/** A check token: listed with its binding, `evaluated: false` (`spec-017` §6.1, P4.12 is v1.0). */
+export interface CheckTokenView extends TokenView {
+    readonly evaluated: false;
+}
+/** One phase of a resolved declaration (`spec-017` §7.6). */
+export interface PhaseView {
+    readonly name: string;
+    readonly description: string | null;
+    readonly role: string | null;
+    readonly optional: boolean;
+    /** The role's directives, role-bound and global, ascending by id (`spec-012` §5); empty without a role. */
+    readonly directives: readonly {
+        readonly id: string;
+        readonly title: string;
+    }[];
+    /** That resolution's warnings (`resolveRoleDirectives`), or why none was made. */
+    readonly directiveWarnings: readonly string[];
+    readonly actions: readonly TokenView[];
+    readonly checks: {
+        readonly pre: readonly CheckTokenView[];
+        readonly post: readonly CheckTokenView[];
+    };
+    /** Each entry with its owner type (`null`: no element, or an implicit owner) and whether it is evidence (§4.3). */
+    readonly produces: readonly {
+        readonly pattern: string;
+        readonly owner: string | null;
+        readonly evidence: boolean;
+    }[];
+    readonly approval: {
+        readonly byRole: string;
+    } | {
+        readonly byPerson: string;
+    } | null;
+    readonly awaits: {
+        readonly party: string;
+        readonly evidence: CheckTokenView;
+    } | null;
+    readonly fallback: {
+        readonly step: string;
+        readonly setState: string | null;
+    } | null;
+    /** `iterate_over` and its filter (§4.6). */
+    readonly iterate: {
+        readonly over: string;
+        readonly where: Readonly<Record<string, unknown>> | null;
+    } | null;
+    /** A `where` without `iterate_over` (`spec-003` § "Selections"). */
+    readonly selection: {
+        readonly where: Readonly<Record<string, unknown>>;
+    } | null;
+    /** The declared mode, `fresh` when absent (`spec-003` § "Execution independence"). */
+    readonly mode: PhaseMode;
+    readonly allowedModes: readonly PhaseMode[];
+    readonly distinctFrom: readonly string[];
+    readonly cadence: Cadence;
+    /** The evidence kinds the phase declares (§4.3), in the deduction's order. */
+    readonly evidence: readonly EvidenceKind[];
+    readonly include: string | null;
+    /** The included workflow, resolved the same way, nested under this phase (P4.7 sc. 2). */
+    readonly sub: WorkflowView | null;
+}
+/** A workflow's declaration resolved (`spec-017` §7.6). */
+export interface WorkflowView {
+    readonly name: string;
+    /** Repository-relative (`.wingfoil/workflows/custom/<name>.yaml`). */
+    readonly file: string;
+    readonly startable: boolean;
+    readonly includable: boolean;
+    readonly description: string | null;
+    readonly element: string | null;
+    readonly phases: readonly PhaseView[];
+}
+/** `workflow show`'s payload: the resolved declaration with the baseline and the diagnostics (`spec-017` §8). */
+export interface ShowResult {
+    readonly baseline: Baseline;
+    readonly workflow: WorkflowView;
+    readonly diagnostics: readonly Diagnostic[];
+}
+/**
+ * `workflow list`'s answer from one deduction (`spec-017` §7.5): without `all`, the startable workflows and
+ * every includable one a frontier enters; with it, every loaded workflow. Pure.
+ */
+export declare function listWorkflows(workflows: readonly Workflow[], deduction: Deduction, all: boolean): ListResult;
+/**
+ * `workflow list [--all]` at `HEAD` (`spec-017` §7.5).
+ *
+ * @throws `DiagnosticsError` (`VALIDATION`) when the registry at `HEAD` has a `spec-003` error;
+ *   `StorageError` when git cannot answer.
+ */
+export declare function workflowListAtHead(root: string, all: boolean): ListResult;
+/** What resolving one declaration reads, all at the snapshot's commit. */
+export interface ShowInputs {
+    readonly workflows: readonly Workflow[];
+    /** Each workflow's file, repository-relative, parallel to `workflows`. */
+    readonly workflowFiles: readonly string[];
+    readonly memoryYaml: MemoryYaml | null;
+    readonly bindings: BindingsYaml | null;
+    readonly rolesYaml: RolesYaml | null;
+    readonly directiveFiles: readonly DirectiveFile[];
+}
+/**
+ * The evidence kinds `phase` declares (`spec-017` §4.3), by the rules the deduction's leaf step applies
+ * (`src/workflow/deduce.ts`), in its order: a plain `include` is `include` alone (§4.5); otherwise
+ * `include` for an `iterate_over`, `state` (`declaresState`, shared), `created`, `produces` (string
+ * entries with an explicit owner), `selection`, `awaits`, then `record` for an `awaits`, a phase with
+ * no kind but `created`, or an `approval:` whose phase holds no gate (`holdsGate: false`, §5.1, task-225).
+ */
+export declare function declaredEvidenceKinds(workflow: Workflow, p: number, boundType: string | null, holdsGate: boolean): EvidenceKind[];
+/**
+ * `workflow show <ref>`'s answer (`spec-017` §7.6, §10): `ref` names a loaded workflow, or an open instance
+ * standing for its workflow; anything else is `NOT_FOUND` `unknown workflow: <ref>`. Pure.
+ */
+export declare function showWorkflow(inputs: ShowInputs, deduction: Deduction, ref: string): CoreResult<ShowResult>;
+/**
+ * `workflow show <ref>` at `HEAD` (`spec-017` §7.6): the deduction snapshot (which carries `bindings.yaml`),
+ * then `roles.yaml` and the directive files at the snapshot's commit.
+ *
+ * @throws `DiagnosticsError` (`VALIDATION`) when the registry at `HEAD` has a `spec-003` error; a
+ *   `ValidationError` for an invalid `roles.yaml` or directive file at `HEAD`; `StorageError` when git
+ *   cannot answer.
+ */
+export declare function workflowShowAtHead(root: string, ref: string): CoreResult<ShowResult>;
+//# sourceMappingURL=workflow-list-show.d.ts.map