@aiwg/cli 2026.9.19 → 2026.9.21

package/dist/src/decision/graph-flow.js

@@ -0,0 +1,105 @@
+import { planDecisionGraph, DecisionGraphError } from './graph.js';
+import { effectiveGraphCeilings } from './graph-evidence.js';
+/** Flow gate ID guarding one node of an approval stage. The gate is an existing
+ * Flow `gate` node: Flow refuses to invoke it until the host approves it. */
+export function decisionGraphApprovalGateId(nodeId) { return `approve-${nodeId}`; }
+/** Compile an authorized decision DAG into existing Flow skill nodes. No new executor/node kind. */
+export function decisionGraphToFlow(graph, options) {
+    const plan = planDecisionGraph(graph, options.resolvedPins);
+    const approvalStages = new Set(options.approvalStages ?? []);
+    if (approvalStages.size !== (options.approvalStages ?? []).length || [...approvalStages].some(stage => !Number.isSafeInteger(stage) || stage < 1 || !plan.stages.some(s => s.stage === stage))) {
+        throw new DecisionGraphError('invalid approval stage');
+    }
+    if (!/^aiwg:skill:[a-f0-9]{16}$/.test(options.decisionSkillId) || !graph.terminals.includes(options.terminal)) {
+        throw new DecisionGraphError('unauthorized Flow skill or terminal');
+    }
+    // Flow's v1alpha1 IDs are lowercase DNS labels. Never silently rename identities.
+    if ([graph.id, ...graph.nodes.map(n => n.id), ...graph.nodes.flatMap(n => [...n.input, ...n.output])]
+        .some(id => !/^[a-z][a-z0-9-]*$/.test(id)))
+        throw new DecisionGraphError('graph identity incompatible with Flow');
+    const reserved = new Set(['subject', 'target', 'model', 'egress', 'state-digest', 'definition-pin', 'binding-pin']);
+    if (graph.nodes.some(n => n.input.some(name => reserved.has(name)) || n.output.length === 0) ||
+        graph.id.length > 63 || graph.id.endsWith('-'))
+        throw new DecisionGraphError('graph incompatible with Flow bindings');
+    const ceilings = effectiveGraphCeilings(graph, ...(options.ceilings ?? []));
+    const names = new Map(graph.nodes.map(n => [n.id, n]));
+    const guards = new Map();
+    for (const edge of plan.edges) {
+        if (!edge.when)
+            continue;
+        const name = `condition-${edge.from}-${edge.when.source}`;
+        guards.set(`${edge.from}.${edge.when.source}`, name);
+    }
+    const gated = new Set(plan.stages.filter(stage => approvalStages.has(stage.stage)).flatMap(stage => stage.nodes));
+    for (const id of gated) {
+        const gate = decisionGraphApprovalGateId(id);
+        if (names.has(gate) || gate.length > 63)
+            throw new DecisionGraphError('approval gate identity incompatible with Flow');
+    }
+    const nodes = plan.stages.flatMap(stage => stage.nodes.flatMap(id => {
+        const n = names.get(id);
+        const incoming = plan.edges.filter(edge => edge.to === id);
+        const predecessors = [...new Set(incoming.map(e => e.from))].sort();
+        // A gate mirrors its node's readiness (same predecessors and guarded routes),
+        // so approval is requested only for a node that would otherwise run.
+        const gate = gated.has(id) ? [{ id: decisionGraphApprovalGateId(id), kind: 'gate',
+                phase: `stage-${stage.stage}`, dependsOn: predecessors, inputs: [], outputs: [],
+                capabilities: [], permissions: [], sideEffectMode: 'none' }] : [];
+        const dependsOn = [...predecessors, ...gate.map(g => g.id)].sort();
+        return [...gate, {
+                id, kind: 'skill', ref: options.decisionSkillId,
+                phase: `stage-${stage.stage}`,
+                ...(dependsOn.length ? { dependsOn } : {}),
+                inputs: [
+                    { name: 'subject', schema: { type: 'string' }, value: n.subject },
+                    { name: 'target', schema: { type: 'string' }, value: n.target },
+                    { name: 'model', schema: { type: 'string' }, value: n.model },
+                    { name: 'egress', schema: { type: 'string' }, value: n.egress },
+                    { name: 'state-digest', schema: { type: 'string' }, value: n.stateDigest },
+                    { name: 'definition-pin', schema: { type: 'object' }, value: n.definition },
+                    { name: 'binding-pin', schema: { type: 'object' }, value: n.binding },
+                    ...incoming.map(e => ({ name: e.destination, schema: { type: ['object', 'array', 'string', 'number', 'boolean', 'null'] }, from: `${e.from}.${e.source}` })),
+                ],
+                outputs: n.output.map(name => {
+                    const guard = guards.get(`${id}.${name}`);
+                    return { name, schema: guard ? { type: 'boolean' } : { type: ['object', 'array', 'string', 'number', 'boolean', 'null'] },
+                        ...(guard ? { state: guard } : {}) };
+                }),
+                capabilities: [], permissions: [], sideEffectMode: 'none',
+                retry: { limit: 0, backoff: 'none', on: ['failure'] },
+            }];
+    }));
+    const terminalNode = names.get(options.terminal);
+    if (terminalNode.output.length < 1)
+        throw new DecisionGraphError('terminal requires an output');
+    // Existing Flow tracks run/node/activation/invocation identity and enforces its
+    // own permission, retry, approval, trace and resource policies. These are ceilings,
+    // not a grant for inference: the host adapter still controls actual transport.
+    // Each approval wave costs one Flow activation but no decision attempt.
+    return {
+        apiVersion: 'flow.aiwg.io/v1alpha1', kind: 'FlowGraph',
+        metadata: { name: graph.id },
+        spec: {
+            entry: [graph.entry], candidates: [{ id: options.decisionSkillId, kind: 'skill' }],
+            state: { fields: [...guards.values()].sort().map(name => ({ name, schema: { type: 'boolean' }, reducer: 'replace' })) },
+            permissions: [], capabilities: [],
+            ceilings: { activations: ceilings.attempts + approvalStages.size, tokens: ceilings.tokens,
+                costUsd: ceilings.costMicros / 1_000_000, timeMs: ceilings.deadlineMs, concurrency: ceilings.concurrency },
+            nodes, routes: [...new Set(plan.edges.map(e => `${e.from}:${e.to}`))].sort().flatMap(pair => {
+                const [from, to] = pair.split(':');
+                const matches = plan.edges.filter(e => e.from === from && e.to === to);
+                const predicates = [...new Set(matches.map(e => e.when ? `${guards.get(`${e.from}.${e.when.source}`)} == ${e.when.equals}` : 'always'))];
+                if (predicates.length !== 1)
+                    throw new DecisionGraphError('conflicting guards on Flow route');
+                const when = predicates[0] === 'always' ? {} : { when: { expression: `state.${predicates[0]}` } };
+                return [{ from: from, to: to, ...when },
+                    ...(gated.has(to) ? [{ from: from, to: decisionGraphApprovalGateId(to), ...when }] : [])];
+            }),
+            joins: [], failure: { onNodeFailure: 'fail', maxFailures: 0 },
+            output: { mode: 'final-only', from: `${options.terminal}.${terminalNode.output[0]}`,
+                schema: { type: ['object', 'array', 'string', 'number', 'boolean', 'null'] } },
+            trace: { level: 'metadata', redact: [] },
+        },
+    };
+}
+//# sourceMappingURL=graph-flow.js.map

package/dist/src/decision/graph-parallel.js

@@ -0,0 +1,79 @@
+import { canonicalJson } from '../security/artifact-trust.js';
+import { correlateAtomicBatch, decisionBatchQuestionId } from './batch.js';
+import { DecisionGraphError, planDecisionGraph } from './graph.js';
+/** Flow parallelDispatch seam. Native batching is strictly opt-in and atomic;
+ * otherwise the existing admitted invokeNode handles bounded fan-out.
+ */
+export function decisionGraphParallelDispatch(graph, plan, options) {
+    const pins = new Set(graph.nodes.flatMap(n => [n.definition.digest, n.binding.digest]));
+    if (canonicalJson(plan) !== canonicalJson(planDecisionGraph(graph, pins)))
+        throw new DecisionGraphError('graph/plan mismatch');
+    return async (requests, invokeNode) => {
+        const ids = new Set(requests.map(r => r.node.id));
+        if (ids.size !== requests.length)
+            throw new DecisionGraphError('duplicate Flow parallel node');
+        const groups = [];
+        const assigned = new Set();
+        for (const stage of plan.stages)
+            for (const batch of stage.batches) {
+                const group = requests.filter(r => batch.includes(r.node.id)).sort((a, b) => a.node.id.localeCompare(b.node.id));
+                if (group.length > 1) {
+                    groups.push(group);
+                    group.forEach(r => assigned.add(r.node.id));
+                }
+            }
+        for (const request of requests)
+            if (!assigned.has(request.node.id))
+                groups.push([request]);
+        const settled = new Map();
+        await Promise.all(groups.map(async (group) => {
+            if (group.length === 1 || !options.canBatch(group) ||
+                new Set(group.map(r => canonicalJson(r.inputs))).size !== 1) {
+                const results = await Promise.all(group.map(r => invokeNode(r)));
+                group.forEach((r, i) => settled.set(r.node.id, results[i]));
+                return;
+            }
+            const stages = new Set(group.map(r => r.node.phase));
+            if (stages.size !== 1 || group.some(r => r.node.kind !== 'skill' || r.node.retry?.limit !== 0 ||
+                r.node.sideEffectMode !== 'none' || !/^stage-(0|[1-9]\d*)$/.test(r.node.phase ?? ''))) {
+                throw new DecisionGraphError('invalid native batch stage');
+            }
+            const stage = Number(group[0].node.phase.slice(6));
+            const estimates = group.map(r => options.estimate(r));
+            if (estimates.some(e => !e || !Number.isSafeInteger(e.costMicros) || e.costMicros < 1 ||
+                !Number.isSafeInteger(e.tokens) || e.tokens < 1))
+                throw new DecisionGraphError('missing native batch estimate');
+            const finish = options.ledger.reserveBatch(stage, estimates);
+            try {
+                const ids = group.map(r => decisionBatchQuestionId(r.node.id));
+                const correlated = correlateAtomicBatch(ids, await options.invokeNativeBatch(group));
+                const values = ids.map(id => correlated.get(id));
+                values.forEach((value, index) => {
+                    const bound = estimates[index];
+                    // An abstention inside an atomic batch fails the whole batch closed.
+                    if (!value || !value.usage || (value.status ?? 'ok') !== 'ok' || !Number.isSafeInteger(value.attempts) || value.attempts < 1 ||
+                        !Number.isSafeInteger(value.usage.tokens) || value.usage.tokens < 0 ||
+                        !Number.isFinite(value.usage.costUsd) || value.usage.costUsd < 0 ||
+                        !Number.isSafeInteger(value.usage.timeMs) || value.usage.timeMs < 0 ||
+                        value.attempts > bound.attempts || value.usage.tokens > bound.tokens ||
+                        Math.ceil(value.usage.costUsd * 1_000_000) > bound.costMicros) {
+                        throw new DecisionGraphError('invalid native batch usage');
+                    }
+                });
+                values.forEach((value, index) => finish[index]({ attempts: value.attempts,
+                    tokens: value.usage.tokens, costMicros: Math.ceil(value.usage.costUsd * 1_000_000) }));
+                group.forEach((r, index) => {
+                    settled.set(r.node.id, values[index]);
+                    options.onObservation?.({ request: r, response: values[index] });
+                });
+                options.onNativeBatch?.(group.map(r => r.node.id));
+            }
+            catch (error) {
+                options.ledger.cancel();
+                throw error; // Never retry an uncertain native batch as individual calls.
+            }
+        }));
+        return requests.map(r => settled.get(r.node.id));
+    };
+}
+//# sourceMappingURL=graph-parallel.js.map

package/dist/src/decision/graph-patterns.js

@@ -0,0 +1,20 @@
+import { DecisionGraphError } from './graph.js';
+/** Deterministic, bounded ranking primitive for shortlist/rerank and taxonomy beams.
+ * The trusted caller supplies candidate IDs and scores; model evidence cannot widen
+ * the graph or confer action authority. This primitive performs no dispatch.
+ */
+export function selectDecisionBeam(candidates, width, ceiling) {
+    if (!Number.isSafeInteger(width) || width < 1 || !Number.isSafeInteger(ceiling) || ceiling < 1 || width > ceiling) {
+        throw new DecisionGraphError('invalid beam width');
+    }
+    const ids = new Set();
+    for (const candidate of candidates) {
+        if (!/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/.test(candidate.id) || ids.has(candidate.id) ||
+            typeof candidate.score !== 'number' || !Number.isFinite(candidate.score))
+            throw new DecisionGraphError('invalid beam candidate');
+        ids.add(candidate.id);
+    }
+    // Explicit secondary key: binary code-point order, never locale or completion order.
+    return [...candidates].sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)).slice(0, width);
+}
+//# sourceMappingURL=graph-patterns.js.map

package/dist/src/decision/graph-run-store.js

@@ -0,0 +1,66 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, link, unlink, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { canonicalJson } from '../security/artifact-trust.js';
+import { admitEntry } from './entry.js';
+import { DecisionGraphError } from './graph.js';
+/** Immutable create-once graph receipt store. Digest detects accidental changes;
+ * without a host-supplied authenticated storage layer it does not prove origin.
+ * Flow checkpoint and dispatcher receipts remain their own durable authorities.
+ */
+export class FileGraphRunReceiptStore {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    path(id) {
+        if (!/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/.test(id))
+            throw new DecisionGraphError('invalid graph receipt id');
+        return join(this.directory, `${id}.json`);
+    }
+    async create(id, receipt) {
+        const destination = this.path(id);
+        this.verify(receipt);
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const temporary = join(this.directory, `.${randomUUID()}.tmp`);
+        const handle = await open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(canonicalJson(receipt));
+            await handle.sync();
+        }
+        catch (error) {
+            await handle.close();
+            await unlink(temporary);
+            throw error;
+        }
+        await handle.close();
+        try {
+            // link is exclusive: another writer cannot replace the existing receipt.
+            await link(temporary, destination);
+        }
+        finally {
+            await unlink(temporary);
+        }
+    }
+    async read(id) {
+        const value = JSON.parse(await readFile(this.path(id), 'utf8'));
+        this.verify(value);
+        return value;
+    }
+    verify(value) {
+        try {
+            admitEntry(value);
+        }
+        catch {
+            throw new DecisionGraphError('invalid graph receipt');
+        }
+        if (value.schemaVersion !== 'decision-graph-run/v1' || typeof value.receiptDigest !== 'string') {
+            throw new DecisionGraphError('invalid graph receipt');
+        }
+        const { receiptDigest, ...body } = value;
+        if (receiptDigest !== `sha256:${createHash('sha256').update(canonicalJson(body)).digest('hex')}`) {
+            throw new DecisionGraphError('graph receipt digest mismatch');
+        }
+    }
+}
+//# sourceMappingURL=graph-run-store.js.map

package/dist/src/decision/graph-run.js

@@ -0,0 +1,166 @@
+import { canonicalJson } from '../security/artifact-trust.js';
+import { createHash } from 'node:crypto';
+import { admitEntry } from './entry.js';
+import { DecisionGraphError } from './graph.js';
+import { auditGraphEvidence } from './graph-evidence.js';
+import { selectDecisionBeam } from './graph-patterns.js';
+import { decisionGraphApprovalGateId } from './graph-flow.js';
+/** Cross-check Flow results against the host's append-only invocation observations.
+ * If an observed Flow invocation is absent, incomplete, or tampered with, fail closed.
+ * The host must persist this receipt atomically alongside its Flow checkpoint.
+ */
+export function finalizeDecisionGraphRun(graph, plan, report, records, ceilings = [], unknownCostBoundMicros, nativeBatches = [], approvalStages = []) {
+    try {
+        admitEntry({ graph, plan, ceilings, runId: report.runId, status: report.status,
+            results: Object.fromEntries(Object.entries(report.results).map(([id, value]) => [id, value.outputs])),
+            completed: report.checkpoint.completed, skipped: report.checkpoint.skipped,
+            routes: report.trace.filter(item => item.type === 'route-evaluated').map(item => ({ from: item.from ?? '', to: item.to ?? '', active: item.active === true })),
+            records: records.map(({ request, response }) => ({ node: request.node.id, runId: request.runId,
+                outputs: response.outputs, attempts: response.attempts, usage: response.usage })),
+            nativeBatches: nativeBatches.map(group => [...group].sort()), approvalStages: [...approvalStages],
+            ...(unknownCostBoundMicros === undefined ? {} : { unknownCostBoundMicros }) });
+    }
+    catch {
+        throw new DecisionGraphError('graph run admission denied');
+    }
+    if (new Set(approvalStages).size !== approvalStages.length ||
+        approvalStages.some(stage => stage < 1 || !plan.stages.some(s => s.stage === stage)))
+        throw new DecisionGraphError('invalid approval stage');
+    // A paused run is waiting for an approval; it has no outcome yet.
+    if (report.status === 'paused')
+        throw new DecisionGraphError('Flow graph run is not final');
+    const gates = new Map(plan.stages.filter(stage => approvalStages.includes(stage.stage))
+        .flatMap(stage => stage.nodes.map(id => [decisionGraphApprovalGateId(id), { nodeId: id, stage: stage.stage }])));
+    if (report.checkpoint.completed.some(id => !gates.has(id) && !graph.nodes.some(n => n.id === id))) {
+        throw new DecisionGraphError('unknown Flow graph node');
+    }
+    const completed = report.checkpoint.completed.filter(id => !gates.has(id));
+    if ([...gates].some(([gate, { nodeId }]) => completed.includes(nodeId) && !report.checkpoint.completed.includes(gate))) {
+        throw new DecisionGraphError('gated node ran without approval');
+    }
+    const observed = new Map();
+    for (const { request, response } of records) {
+        const status = response.status ?? 'ok';
+        if (observed.has(request.node.id) || request.runId !== report.runId || !graph.nodes.some(n => n.id === request.node.id) ||
+            (status === 'ok' ? !completed.includes(request.node.id) || !report.results[request.node.id] ||
+                canonicalJson(report.results[request.node.id].outputs) !== canonicalJson(response.outputs)
+                : completed.includes(request.node.id) || !report.checkpoint.failed?.includes(request.node.id) ||
+                    (status !== 'abstained' && status !== 'unsupported') || Object.keys(response.outputs).length)) {
+            throw new DecisionGraphError('Flow graph observation mismatch');
+        }
+        if (!Number.isSafeInteger(response.attempts) || response.attempts < 1 ||
+            !Number.isSafeInteger(response.usage.tokens) || response.usage.tokens < 0 ||
+            !Number.isSafeInteger(response.usage.timeMs) || response.usage.timeMs < 0 ||
+            !Number.isFinite(response.usage.costUsd) || response.usage.costUsd < 0)
+            throw new DecisionGraphError('invalid Flow graph usage');
+        observed.set(request.node.id, { node: request.node.id, status, output: response.outputs,
+            attempts: response.attempts, tokens: response.usage.tokens, costMicros: Math.ceil(response.usage.costUsd * 1_000_000),
+            durationMs: response.usage.timeMs, used: status === 'ok',
+            flow: { runId: request.runId, nodeRunId: request.nodeRunId,
+                activationId: request.activationId, invocationKey: request.invocationKey } });
+    }
+    // Flow v1alpha1 reports guarded-off destinations as NO_RUNNABLE_NODES rather
+    // than skipped. Only interpret such nodes as unused if every incoming route
+    // has an explicit inactive trace from a completed predecessor (or a skipped
+    // predecessor). Never normalize an unrelated failed Flow run to success.
+    const inactive = new Set(report.checkpoint.skipped);
+    for (const stage of plan.stages) {
+        for (const id of stage.nodes) {
+            if (completed.includes(id) || inactive.has(id))
+                continue;
+            const incoming = plan.edges.filter(e => e.to === id);
+            if (incoming.length && incoming.every(e => inactive.has(e.from) ||
+                report.trace.some(event => event.type === 'route-evaluated' && event.from === e.from && event.to === id && event.active === false))) {
+                inactive.add(id);
+            }
+        }
+    }
+    for (const id of inactive) {
+        if (observed.has(id))
+            throw new DecisionGraphError('Flow node both skipped and observed');
+        observed.set(id, { node: id, status: 'skipped', output: {}, attempts: 0, tokens: 0,
+            costMicros: 0, durationMs: 0, used: false });
+    }
+    // A node that abstained or was unsupported stopped the graph (as does a cancelled
+    // run): nodes it prevented from dispatching are recorded with zero usage.
+    const stopped = report.status === 'cancelled' ? 'cancelled' :
+        [...observed.values()].some(obs => obs.status !== 'ok' && obs.status !== 'skipped') ? 'skipped' : null;
+    if (stopped)
+        for (const node of graph.nodes) {
+            if (observed.has(node.id))
+                continue;
+            observed.set(node.id, { node: node.id, status: stopped, output: {}, attempts: 0, tokens: 0,
+                costMicros: 0, durationMs: 0, used: false });
+        }
+    // Flow counts only successful node runs, including approved zero-cost gates.
+    const flowRecords = records.filter(item => (item.response.status ?? 'ok') === 'ok');
+    const approvedGates = report.checkpoint.completed.filter(id => gates.has(id)).length;
+    if (completed.length !== flowRecords.length || observed.size !== graph.nodes.length ||
+        report.realizedResources.nodeRuns !== flowRecords.length + approvedGates ||
+        report.realizedResources.tokens !== flowRecords.reduce((sum, item) => sum + item.response.usage.tokens, 0) ||
+        Math.abs(report.realizedResources.costUsd - flowRecords.reduce((sum, item) => sum + item.response.usage.costUsd, 0)) > 1e-9) {
+        throw new DecisionGraphError('missing Flow graph observation');
+    }
+    const candidates = graph.terminals.filter(id => observed.get(id)?.status === 'ok');
+    // Prefer the deepest completed terminal, with stable ID tie ordering.
+    // An invoked fallback supersedes its verifier; a guarded-off fallback does not.
+    const deepest = Math.max(-1, ...candidates.map(id => graph.nodes.find(n => n.id === id).stage));
+    const terminal = candidates.length ? selectDecisionBeam(candidates.map(id => ({ id, score: graph.nodes.find(n => n.id === id).stage === deepest ? 1 : 0 })), 1, 1)[0].id : null;
+    // Only the chosen terminal's transitive predecessors contributed to the
+    // selected evidence. Every speculative observation still retains its usage.
+    const used = new Set();
+    if (terminal) {
+        const pending = [terminal];
+        while (pending.length) {
+            const id = pending.pop();
+            if (used.has(id))
+                continue;
+            used.add(id);
+            pending.push(...plan.edges.filter(edge => edge.to === id).map(edge => edge.from));
+        }
+    }
+    for (const obs of observed.values())
+        if (obs.status === 'ok')
+            obs.used = used.has(obs.node);
+    const evidence = auditGraphEvidence(graph, plan, [...observed.values()], ceilings, unknownCostBoundMicros);
+    let outcome = evidence.outcome;
+    if (report.status === 'cancelled')
+        outcome = 'cancelled';
+    else if (report.status !== 'completed' && outcome === 'complete' &&
+        !(report.status === 'failed' && report.stopReason.startsWith('no runnable nodes remain:') &&
+            completed.length + inactive.size === graph.nodes.length))
+        outcome = 'error';
+    else if (outcome === 'complete' && !terminal)
+        outcome = graph.pattern === 'shortlist-rerank' ? 'empty-shortlist' : 'incomplete-evidence';
+    const value = outcome === 'complete' && terminal ? observed.get(terminal).output : null;
+    const declared = nativeBatches.map(group => canonicalJson([...group].sort()));
+    const permitted = new Set(plan.stages.flatMap(stage => stage.batches.map(group => canonicalJson(group))));
+    if (declared.length !== new Set(declared).size || declared.some(group => !permitted.has(group))) {
+        throw new DecisionGraphError('unrecognized native batch receipt');
+    }
+    const batches = plan.stages.flatMap(stage => stage.batches.map(nodes => ({ stage: stage.stage, nodes,
+        resultDigests: nodes.map(id => evidence.stages[stage.stage].nodes.find(node => node.id === id).resultDigest),
+        executedNative: declared.includes(canonicalJson(nodes)) })));
+    const started = report.trace.filter(event => event.type === 'node-started');
+    const approvals = started.filter(event => event.nodeId && gates.has(event.nodeId)).map(event => {
+        if (!event.nodeRunId || !Number.isSafeInteger(event.activation))
+            throw new DecisionGraphError('invalid Flow approval lineage');
+        const gate = gates.get(event.nodeId);
+        return { gate: event.nodeId, nodeId: gate.nodeId, stage: gate.stage, nodeRunId: event.nodeRunId, activation: event.activation };
+    }).sort((a, b) => a.gate.localeCompare(b.gate) || a.activation - b.activation);
+    const attempts = started.filter(event => !event.nodeId || !gates.has(event.nodeId)).map(event => {
+        if (!event.nodeId || !event.nodeRunId || !event.invocationKey ||
+            !Number.isSafeInteger(event.attempt) || !Number.isSafeInteger(event.activation)) {
+            throw new DecisionGraphError('invalid Flow attempt lineage');
+        }
+        return { nodeId: event.nodeId, nodeRunId: event.nodeRunId, invocationKey: event.invocationKey,
+            attempt: event.attempt, activation: event.activation };
+    }).sort((a, b) => a.nodeId.localeCompare(b.nodeId) || a.attempt - b.attempt);
+    if (attempts.length < records.length)
+        throw new DecisionGraphError('missing Flow attempt lineage');
+    const receipt = { schemaVersion: 'decision-graph-run/v1', graphDigest: plan.graphDigest,
+        flowRunId: report.runId, flowStatus: report.status, flowStopReason: report.stopReason,
+        evidence, terminal, outcome, value, batches, attempts, approvals };
+    return { ...receipt, receiptDigest: `sha256:${createHash('sha256').update(canonicalJson(receipt)).digest('hex')}` };
+}
+//# sourceMappingURL=graph-run.js.map

package/dist/src/decision/graph-skill-bridge.js

@@ -0,0 +1,91 @@
+import { execFile } from 'node:child_process';
+import { chmod, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { resolveRoutableCapability } from '../artifacts/capability-resolver.js';
+import { parseDecisionJson } from './entry.js';
+import { DecisionGraphError } from './graph.js';
+import { assertDecisionFlowPins, assertUnknownCostBound, decisionFlowNode, decisionFlowResponse } from './graph-decision-bridge.js';
+/** Resolve the packaged `decision-evaluate` skill: its stable catalog ID becomes the
+ * Flow node ref, and its declared script entrypoint is the only program invoked.
+ * Neither comes from graph evidence.
+ */
+export async function resolveDecisionEvaluateSkill(frameworkRoot) {
+    const skill = await resolveRoutableCapability(frameworkRoot, 'skill', 'decision-evaluate');
+    if (!/^aiwg:skill:[a-f0-9]{16}$/.test(skill.id))
+        throw new DecisionGraphError('invalid decision-evaluate skill ID');
+    const manifest = resolve(frameworkRoot, skill.source.path);
+    const frontmatter = /^---\n([\s\S]*?)\n---/.exec(await readFile(manifest, 'utf8'))?.[1] ?? '';
+    const entrypoint = /^\s+entrypoint:\s*(\S+)\s*$/m.exec(frontmatter)?.[1];
+    const scriptPath = entrypoint ? resolve(dirname(manifest), entrypoint) : '';
+    const inside = relative(dirname(manifest), scriptPath);
+    if (!entrypoint || !inside || inside.startsWith('..') || isAbsolute(inside))
+        throw new DecisionGraphError('invalid decision-evaluate entrypoint');
+    return { id: skill.id, scriptPath };
+}
+/** Default runner: executes the skill entrypoint with a minimal environment.
+ * Only PATH, the opt-in flag and host-listed variables reach the child process.
+ */
+export function runDecisionEvaluateSkill(run) {
+    return new Promise(done => {
+        execFile(process.execPath, [run.scriptPath, '--request', run.requestPath], {
+            cwd: dirname(run.requestPath), timeout: run.timeoutMs, maxBuffer: 16 * 1024 * 1024,
+            env: { PATH: process.env.PATH ?? '', ...run.env, AIWG_DECISION_ENABLED: '1' },
+        }, (error, stdout) => done({ code: error ? (typeof error.code === 'number' ? error.code : -1) : 0, stdout }));
+    });
+}
+/** Flow skill invoker that runs the shipped decision-evaluate skill for every graph node.
+ * Each call writes a private dispatcher request (and, for a dependent node, only its
+ * declared projected evidence as input), runs the skill script, and accepts only a
+ * RulesetResult for the same Flow run/invocation and binding pin. The skill's own
+ * stderr is never propagated into graph errors.
+ */
+export function decisionEvaluateSkillFlowInvoker(graph, host) {
+    assertUnknownCostBound(host);
+    if (!isAbsolute(host.workDirectory))
+        throw new DecisionGraphError('skill work directory must be absolute');
+    return async (flow) => {
+        const { node, input } = decisionFlowNode(graph, flow);
+        const base = host.request(node.id);
+        const paths = [base.rulesetPath, base.bindingPath, ...base.definitionPaths,
+            ...(base.inputPath === undefined ? [] : [base.inputPath]), ...Object.values(base.adapterModules ?? {}),
+            ...(base.receiptDirectory === undefined ? [] : [base.receiptDirectory])];
+        if (!base.definitionPaths.length || paths.some(path => typeof path !== 'string' || !isAbsolute(path)) ||
+            (node.id === graph.entry && base.inputPath === undefined))
+            throw new DecisionGraphError('invalid decision-evaluate request');
+        const load = async (path) => parseDecisionJson(await readFile(path, 'utf8'));
+        assertDecisionFlowPins(node, await load(base.bindingPath), await Promise.all(base.definitionPaths.map(load)));
+        const directory = await mkdtemp(join(host.workDirectory, 'decision-evaluate-'));
+        try {
+            await chmod(directory, 0o700);
+            let inputPath = base.inputPath;
+            if (node.id !== graph.entry) {
+                inputPath = join(directory, 'input.json');
+                await writeFile(inputPath, JSON.stringify(input), { mode: 0o600, flag: 'wx' });
+            }
+            const requestPath = join(directory, 'request.json');
+            await writeFile(requestPath, JSON.stringify({ ...base, inputPath, runId: flow.runId, invocationId: flow.invocationKey }), { mode: 0o600, flag: 'wx' });
+            const outcome = await (host.run ?? runDecisionEvaluateSkill)({ scriptPath: host.skill.scriptPath, requestPath,
+                env: { ...(host.env ?? {}) }, timeoutMs: host.timeoutMs ?? 60_000 });
+            // Exit 1 still carries an error/cancelled RulesetResult; anything else is a failure.
+            if (outcome.code !== 0 && outcome.code !== 1)
+                throw new DecisionGraphError('decision-evaluate skill failed');
+            let result;
+            try {
+                result = parseDecisionJson(outcome.stdout);
+            }
+            catch {
+                throw new DecisionGraphError('invalid decision-evaluate output');
+            }
+            if (!result || result.kind !== 'RulesetResult' || !result.spec || result.spec.runId !== flow.runId ||
+                result.spec.invocationId !== flow.invocationKey || result.spec.binding?.digest !== node.binding.digest ||
+                !result.spec.evaluations || typeof result.spec.evaluations !== 'object') {
+                throw new DecisionGraphError('decision-evaluate result does not match its Flow invocation');
+            }
+            return decisionFlowResponse(graph, node, result, host);
+        }
+        finally {
+            await rm(directory, { recursive: true, force: true });
+        }
+    };
+}
+//# sourceMappingURL=graph-skill-bridge.js.map

package/dist/src/decision/graph-templates.js

@@ -0,0 +1,56 @@
+import { planDecisionGraph } from './graph.js';
+function validated(graph, pins) {
+    return { graph, plan: planDecisionGraph(graph, pins) };
+}
+/** Entry obtains an explicit shortlist; only its declared candidates reach reranking.
+ * The host projector must set `has-candidates` from the shortlist it projects: when it
+ * is false, reranking never runs and the graph outcome is `empty-shortlist`.
+ */
+export function shortlistRerankTemplate(base) {
+    return validated({ schemaVersion: 'decision-graph/v1', id: base.id, pattern: 'shortlist-rerank',
+        entry: 'shortlist', terminals: ['rerank'], budget: base.budget,
+        nodes: [
+            { ...base.shortlist, id: 'shortlist', stage: 0, input: [], output: ['candidates', 'has-candidates'] },
+            { ...base.rerank, id: 'rerank', stage: 1, input: ['candidates'], output: ['result'] },
+        ], edges: [{ from: 'shortlist', to: 'rerank', source: 'candidates', destination: 'candidates',
+                when: { source: 'has-candidates', equals: true } }] }, base.resolvedPins);
+}
+/** Fixed, caller-authored taxonomy candidates fan out; no model may create new nodes. */
+export function taxonomyBeamTemplate(base) {
+    const ordered = [...base.branches].sort((a, b) => a.id.localeCompare(b.id));
+    if (base.details && base.select.target !== 'beam')
+        throw new Error('guarded beam requires a deterministic selector target');
+    const terminals = base.details ? ordered.map(branch => `detail-${branch.id}`) : ['select'];
+    return validated({ schemaVersion: 'decision-graph/v1', id: base.id, pattern: 'taxonomy-beam',
+        entry: 'taxonomy', terminals, budget: base.budget,
+        nodes: [
+            { ...base.taxonomy, id: 'taxonomy', stage: 0, input: [], output: ['children'] },
+            ...ordered.map(branch => ({ ...branch.config, id: branch.id, stage: 1, input: ['children'], output: ['score'] })),
+            { ...base.select, id: 'select', stage: 2, input: ordered.map(branch => branch.id),
+                output: ['result', ...(base.details ? ordered.map(branch => `chosen-${branch.id}`) : [])] },
+            ...(base.details ? ordered.map(branch => ({ ...base.details, id: `detail-${branch.id}`,
+                stage: 3, input: ['seed'], output: ['result'] })) : []),
+        ], edges: [
+            ...ordered.map(branch => ({ from: 'taxonomy', to: branch.id, source: 'children', destination: 'children' })),
+            ...ordered.map(branch => ({ from: branch.id, to: 'select', source: 'score', destination: branch.id })),
+            ...(base.details ? ordered.map(branch => ({ from: 'select', to: `detail-${branch.id}`,
+                source: 'result', destination: 'seed', when: { source: `chosen-${branch.id}`, equals: true } })) : []),
+        ] }, base.resolvedPins);
+}
+/** A declared boolean from the verifier controls the ordinary-LLM fallback.
+ * If false, verifier is terminal; if true, the fallback result supersedes it.
+ */
+export function extractorVerifierFallbackTemplate(base) {
+    return validated({ schemaVersion: 'decision-graph/v1', id: base.id, pattern: 'extractor-verifier-fallback',
+        entry: 'extractor', terminals: ['verifier', 'fallback'], budget: base.budget,
+        nodes: [
+            { ...base.extractor, id: 'extractor', stage: 0, input: [], output: ['evidence'] },
+            { ...base.verifier, id: 'verifier', stage: 1, input: ['evidence'], output: ['result', 'needs-fallback'] },
+            { ...base.fallback, id: 'fallback', stage: 2, input: ['prior'], output: ['result'] },
+        ], edges: [
+            { from: 'extractor', to: 'verifier', source: 'evidence', destination: 'evidence' },
+            { from: 'verifier', to: 'fallback', source: 'result', destination: 'prior',
+                when: { source: 'needs-fallback', equals: true } },
+        ] }, base.resolvedPins);
+}
+//# sourceMappingURL=graph-templates.js.map