@aiwg/cli 2026.9.20 → 2026.9.24

package/dist/src/decision/file-lifecycle-store.js

@@ -0,0 +1,168 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DECISION_LIFECYCLE_SURFACES } from './lifecycle.js';
+const OPAQUE = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+/** Single-writer local lifecycle journal. Content erasure is delegated per surface. */
+export class FileDecisionLifecycleStore {
+    directory;
+    erasers;
+    constructor(directory, erasers) {
+        this.directory = directory;
+        this.erasers = erasers;
+        if (!directory)
+            throw new Error('Lifecycle storage root required');
+    }
+    async path() {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const info = await lstat(this.directory);
+        if (!info.isDirectory() || info.isSymbolicLink() || (info.mode & 0o077) !== 0) {
+            throw new Error('Lifecycle storage root must be private');
+        }
+        return join(this.directory, 'lifecycle.jsonl');
+    }
+    valid(subject, reference) {
+        if (typeof subject !== 'string' || !OPAQUE.test(subject) || reference &&
+            (!DECISION_LIFECYCLE_SURFACES.includes(reference.surface) || typeof reference.opaqueId !== 'string'
+                || !OPAQUE.test(reference.opaqueId)))
+            throw new Error('Lifecycle reference must be opaque');
+    }
+    async append(entry) {
+        const fd = await open(await this.path(), constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+        try {
+            await fd.writeFile(`${JSON.stringify(entry)}\n`);
+            await fd.sync();
+        }
+        finally {
+            await fd.close();
+        }
+    }
+    async entries() {
+        let fd;
+        try {
+            fd = await open(await this.path(), constants.O_RDONLY | constants.O_NOFOLLOW);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw new Error('Lifecycle journal unavailable');
+        }
+        try {
+            const text = await fd.readFile({ encoding: 'utf8' });
+            const records = text.trim() ? text.trim().split('\n').map(line => JSON.parse(line)) : [];
+            if (records.some(entry => !this.validEntry(entry)))
+                throw new Error();
+            return records;
+        }
+        catch {
+            throw new Error('Lifecycle journal invalid');
+        }
+        finally {
+            await fd.close();
+        }
+    }
+    validEntry(entry) {
+        if (!entry || !['link', 'tombstone', 'hold', 'release'].includes(entry.kind))
+            return false;
+        try {
+            if (entry.kind === 'link') {
+                if (!entry.reference)
+                    return false;
+                this.valid(entry.subject, entry.reference);
+                return true;
+            }
+            if (entry.kind === 'tombstone') {
+                if (!entry.value?.reference)
+                    return false;
+                this.valid(entry.value.subject, entry.value.reference);
+                return Number.isSafeInteger(entry.value.deletedAt) && entry.value.deletedAt >= 0;
+            }
+            const hold = entry.kind === 'hold' ? entry.value : entry.hold;
+            this.valid(hold?.subject);
+            if (!hold.reason || !hold.authorizedBy || !Number.isSafeInteger(hold.expiresAt)
+                || !Array.isArray(hold.scope) || !hold.scope.length
+                || hold.scope.some(surface => !DECISION_LIFECYCLE_SURFACES.includes(surface)))
+                return false;
+            if (entry.kind === 'release') {
+                return entry.subject === hold.subject && !!entry.actor && !!entry.reason
+                    && Number.isSafeInteger(entry.at) && entry.at >= 0;
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async register(subject, reference) {
+        this.valid(subject, reference);
+        await this.append({ kind: 'link', subject, reference });
+    }
+    async links(subject) {
+        this.valid(subject);
+        const records = await this.entries();
+        const registered = records.filter((entry) => entry.kind === 'link' && entry.subject === subject);
+        return [...new Map(registered.map(entry => [`${entry.reference.surface}:${entry.reference.opaqueId}`, entry.reference])).values()];
+    }
+    async tombstone(value) {
+        this.valid(value.subject, value.reference);
+        await this.append({ kind: 'tombstone', value });
+    }
+    async tombstones(subject) {
+        this.valid(subject);
+        return (await this.entries()).flatMap(entry => entry.kind === 'tombstone' && entry.value.subject === subject ? [entry.value] : []);
+    }
+    /**
+     * Resolve a cross-surface reference held by any record. A reference whose target was erased
+     * resolves to an explicit tombstone (without the erased subject) rather than a dangling link.
+     */
+    async resolveReference(reference) {
+        this.valid('opaque-subject', reference);
+        const same = (value) => value.surface === reference.surface && value.opaqueId === reference.opaqueId;
+        const records = await this.entries();
+        const deleted = records.find((entry) => entry.kind === 'tombstone' && same(entry.value.reference));
+        if (deleted)
+            return { state: 'tombstoned', reference: { ...reference }, deletedAt: deleted.value.deletedAt };
+        return records.some(entry => entry.kind === 'link' && same(entry.reference))
+            ? { state: 'linked', reference: { ...reference } } : { state: 'unknown', reference: { ...reference } };
+    }
+    async erase(reference) {
+        this.valid('opaque-subject', reference);
+        const erase = this.erasers[reference.surface];
+        if (!erase)
+            throw new Error('Lifecycle eraser unavailable');
+        try {
+            await erase(reference.opaqueId);
+        }
+        catch {
+            throw new Error('Lifecycle erasure failed');
+        }
+    }
+    async holds(subject) {
+        this.valid(subject);
+        const active = [];
+        for (const entry of await this.entries()) {
+            if (entry.kind === 'hold' && entry.value.subject === subject)
+                active.push(entry.value);
+            if (entry.kind === 'release' && entry.subject === subject) {
+                const index = active.findIndex(hold => JSON.stringify(hold) === JSON.stringify(entry.hold));
+                if (index >= 0)
+                    active.splice(index, 1);
+            }
+        }
+        return active;
+    }
+    async recordHold(hold) {
+        if (!this.validEntry({ kind: 'hold', value: hold }))
+            throw new Error('Lifecycle hold invalid');
+        await this.append({ kind: 'hold', value: hold });
+    }
+    async releaseHold(hold, actor, reason, at) {
+        this.valid(hold.subject);
+        const release = { kind: 'release', subject: hold.subject, hold, actor, reason, at };
+        if (!this.validEntry(release) || !(await this.holds(hold.subject)).some(active => JSON.stringify(active) === JSON.stringify(hold))) {
+            throw new Error('Lifecycle release invalid');
+        }
+        await this.append(release);
+    }
+}
+//# sourceMappingURL=file-lifecycle-store.js.map

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

@@ -0,0 +1,40 @@
+import { DecisionGraphError } from './graph.js';
+import { effectiveGraphCeilings } from './graph-evidence.js';
+import { selectDecisionBeam } from './graph-patterns.js';
+/** A deterministic host-side selector at the existing Flow skill invocation seam.
+ * It cannot create nodes, change pins, dispatch inference or authorize actions.
+ * The host still wraps this with admittedDecisionFlowAdapter for uniform accounting.
+ */
+export function graphBeamFlowInvoker(graph, delegate, ceilings = []) {
+    const nodeStage = graph.nodes.find(n => n.id === 'select')?.stage;
+    const stageWidth = graph.stageBudgets?.find(item => item.stage === nodeStage)?.limits.beamWidth;
+    const width = Math.min(effectiveGraphCeilings(graph, ...ceilings).beamWidth, stageWidth ?? Infinity);
+    return async (request) => {
+        const node = graph.nodes.find(n => n.id === request.node.id);
+        if (node?.target !== 'beam')
+            return delegate(request);
+        if (graph.pattern !== 'taxonomy-beam' || node.id !== 'select' || request.node.kind !== 'skill') {
+            throw new DecisionGraphError('unauthorized beam selector');
+        }
+        const candidates = node.input.map(id => {
+            const score = request.inputs[id];
+            if (typeof score !== 'number' || !Number.isFinite(score))
+                throw new DecisionGraphError('invalid beam score');
+            return { id, score };
+        });
+        if (!candidates.length)
+            throw new DecisionGraphError('empty beam shortlist');
+        const ranked = selectDecisionBeam(candidates, Math.min(width, candidates.length), width).map(item => item.id);
+        const selected = new Set(ranked);
+        const output = { result: ranked };
+        for (const id of node.input) {
+            const flag = `chosen-${id}`;
+            if (node.output.includes(flag))
+                output[flag] = selected.has(id);
+        }
+        if (node.output.some(key => !Object.hasOwn(output, key)))
+            throw new DecisionGraphError('beam selector output mismatch');
+        return { outputs: output, attempts: 1, usage: { tokens: 0, costUsd: 0, timeMs: 0 } };
+    };
+}
+//# sourceMappingURL=graph-beam.js.map

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

@@ -0,0 +1,110 @@
+import { DecisionGraphError, planDecisionGraph } from './graph.js';
+import { effectiveGraphCeilings } from './graph-evidence.js';
+import { canonicalJson } from '../security/artifact-trust.js';
+const empty = () => ({ attempts: 0, tokens: 0, costMicros: 0 });
+const fields = ['attempts', 'tokens', 'costMicros'];
+const safe = (value) => Number.isSafeInteger(value) && value >= 0;
+/** Synchronous reservations protect cumulative and per-stage capacity before adapter calls.
+ * Host estimates must be conservative bounds, including unknown cost. This is not a
+ * network dispatcher; callers retain Flow identities, transport and authorization.
+ */
+export class GraphBudgetLedger {
+    graph;
+    plan;
+    clock;
+    total = empty();
+    stages = new Map();
+    active = new Map();
+    stageStarted = new Map();
+    cancelled = false;
+    started;
+    limits;
+    constructor(graph, plan, ceilings = [], clock = Date.now) {
+        this.graph = graph;
+        this.plan = plan;
+        this.clock = clock;
+        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');
+        this.limits = effectiveGraphCeilings(graph, ...ceilings);
+        this.started = clock();
+        if (!Number.isFinite(this.started))
+            throw new DecisionGraphError('invalid clock');
+    }
+    cancel() { this.cancelled = true; }
+    /** All-or-nothing synchronous batch claim; no remote call occurs before every
+     * member passes stage, graph and concurrency capacity checks. */
+    reserveBatch(stage, estimates) {
+        if (!estimates.length || !estimates.every(e => fields.every(field => safe(e[field])) && e.attempts >= 1)) {
+            throw new DecisionGraphError('invalid graph batch estimate');
+        }
+        const now = this.clock();
+        if (this.cancelled)
+            throw new DecisionGraphError('graph cancelled');
+        if (!Number.isFinite(now) || now < this.started || now - this.started >= this.limits.deadlineMs ||
+            !this.plan.stages.some(s => s.stage === stage))
+            throw new DecisionGraphError('graph batch deadline or stage invalid');
+        const limit = this.graph.stageBudgets?.find(item => item.stage === stage)?.limits ?? this.limits;
+        if (now - (this.stageStarted.get(stage) ?? now) >= limit.deadlineMs)
+            throw new DecisionGraphError('stage deadline exhausted');
+        const total = Object.fromEntries(fields.map(field => [field, estimates.reduce((sum, e) => sum + e[field], 0)]));
+        const spent = this.stages.get(stage) ?? empty();
+        if (estimates.length + (this.active.get(stage) ?? 0) > Math.min(limit.concurrency, this.limits.concurrency) ||
+            fields.some(field => !safe(total[field]) || this.total[field] + total[field] > this.limits[field] ||
+                spent[field] + total[field] > limit[field]))
+            throw new DecisionGraphError('graph batch budget exhausted');
+        return estimates.map(estimate => this.reserveAt(stage, estimate, now));
+    }
+    reserve(stage, estimate) {
+        return this.reserveAt(stage, estimate, this.clock());
+    }
+    reserveAt(stage, estimate, now) {
+        if (this.cancelled)
+            throw new DecisionGraphError('graph cancelled');
+        if (!Number.isFinite(now) || now < this.started || now - this.started >= this.limits.deadlineMs) {
+            throw new DecisionGraphError('graph deadline exhausted');
+        }
+        if (!this.plan.stages.some(s => s.stage === stage))
+            throw new DecisionGraphError('unknown graph stage');
+        if (!fields.every(field => safe(estimate[field])) || estimate.attempts < 1)
+            throw new DecisionGraphError('invalid graph estimate');
+        const stageLimit = this.graph.stageBudgets?.find(item => item.stage === stage)?.limits ?? this.limits;
+        const stageStart = this.stageStarted.get(stage) ?? now;
+        if (now - stageStart >= stageLimit.deadlineMs)
+            throw new DecisionGraphError('stage deadline exhausted');
+        const used = this.stages.get(stage) ?? empty();
+        if ([this.total, used].some((spent, index) => fields.some(field => spent[field] + estimate[field] > (index === 0 ? this.limits : stageLimit)[field]))) {
+            throw new DecisionGraphError('graph budget exhausted');
+        }
+        const count = this.active.get(stage) ?? 0;
+        if (count >= Math.min(this.limits.concurrency, stageLimit.concurrency))
+            throw new DecisionGraphError('graph concurrency exhausted');
+        for (const field of fields) {
+            this.total[field] += estimate[field];
+            used[field] += estimate[field];
+        }
+        this.stages.set(stage, used);
+        this.active.set(stage, count + 1);
+        this.stageStarted.set(stage, stageStart);
+        let settled = false;
+        return (actual) => {
+            if (settled)
+                throw new DecisionGraphError('graph reservation already settled');
+            settled = true;
+            this.active.set(stage, this.active.get(stage) - 1);
+            // Never refund an attempt: even a failed/uncertain dispatch consumes it.
+            const finished = this.clock();
+            if (!fields.every(field => safe(actual[field])) || fields.some(field => actual[field] > estimate[field]) ||
+                !Number.isFinite(finished) || finished < now || finished - this.started > this.limits.deadlineMs ||
+                finished - stageStart > stageLimit.deadlineMs) {
+                this.cancelled = true;
+                throw new DecisionGraphError('graph usage exceeded reservation');
+            }
+            for (const field of ['tokens', 'costMicros']) {
+                this.total[field] -= estimate[field] - actual[field];
+                used[field] -= estimate[field] - actual[field];
+            }
+        };
+    }
+}
+//# sourceMappingURL=graph-budget.js.map

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

@@ -0,0 +1,93 @@
+import { evaluateDecisionRuleset } from './evaluate.js';
+import { artifactPin } from './validate.js';
+import { DecisionGraphError } from './graph.js';
+import { admitEntry } from './entry.js';
+/** Default node status: an unsupported capability, or every evaluation abstaining,
+ * yields no evidence. Hosts with a ruleset-specific policy supply their own. */
+export function decisionResultNodeStatus(result) {
+    const statuses = Object.values(result.spec.evaluations).map(item => item.spec.status);
+    if (result.spec.reason === 'unsupported-capability' || (statuses.length && statuses.every(s => s === 'unsupported')))
+        return 'unsupported';
+    if (statuses.length && statuses.every(s => s === 'abstained'))
+        return 'abstained';
+    return 'ok';
+}
+/** Validate a Flow skill request and return the graph node and its declared projected input. */
+export function decisionFlowNode(graph, flow) {
+    const node = graph.nodes.find(n => n.id === flow.node.id);
+    if (!node || flow.node.kind !== 'skill' || !flow.runId || !flow.invocationKey)
+        throw new DecisionGraphError('invalid Flow decision invocation');
+    const input = {};
+    for (const name of node.input) {
+        if (!Object.hasOwn(flow.inputs, name))
+            throw new DecisionGraphError('missing projected Flow input');
+        input[name] = flow.inputs[name];
+    }
+    return { node, input };
+}
+export function assertDecisionFlowPins(node, binding, definitions) {
+    if (artifactPin(binding).digest !== node.binding.digest ||
+        !definitions.some(def => artifactPin(def).digest === node.definition.digest)) {
+        throw new DecisionGraphError('Flow decision pin mismatch');
+    }
+}
+/** Project a ruleset result through the host projector and account every attempt. */
+export function decisionFlowResponse(graph, node, result, host) {
+    const status = (host.status ?? ((_, value) => decisionResultNodeStatus(value)))(node.id, result);
+    if (!['ok', 'abstained', 'unsupported'].includes(status))
+        throw new DecisionGraphError('invalid decision node status');
+    const output = status === 'ok' ? host.project(node.id, result) : {};
+    try {
+        admitEntry(output);
+    }
+    catch {
+        throw new DecisionGraphError('invalid projected decision result');
+    }
+    if (status === 'ok' && (!output || typeof output !== 'object' || Array.isArray(output) ||
+        Object.keys(output).some(key => !node.output.includes(key)) ||
+        node.output.some(key => !Object.hasOwn(output, key)) ||
+        graph.edges.some(edge => edge.from === node.id && edge.when && typeof output[edge.when.source] !== 'boolean'))) {
+        throw new DecisionGraphError('invalid projected decision outputs');
+    }
+    const attempts = Object.values(result.spec.evaluations).flatMap(e => e.spec.attempts);
+    let tokens = 0, costUsd = 0, timeMs = 0;
+    for (const attempt of attempts) {
+        const inputTokens = attempt.usage.inputTokens;
+        const outputTokens = attempt.usage.outputTokens;
+        if (inputTokens === null || outputTokens === null || !Number.isSafeInteger(inputTokens) || !Number.isSafeInteger(outputTokens)) {
+            throw new DecisionGraphError('unknown graph token usage');
+        }
+        tokens += inputTokens + outputTokens;
+        costUsd += attempt.usage.costUsd ?? host.unknownCostBoundUsd;
+        timeMs += attempt.durationMs;
+    }
+    if (!Number.isSafeInteger(tokens) || !Number.isFinite(costUsd) || !Number.isSafeInteger(timeMs))
+        throw new DecisionGraphError('invalid graph usage');
+    return { outputs: output, attempts: attempts.length || 1, usage: { tokens, costUsd, timeMs },
+        ...(status === 'ok' ? {} : { status }) };
+}
+export function assertUnknownCostBound(host) {
+    if (!Number.isFinite(host.unknownCostBoundUsd) || host.unknownCostBoundUsd <= 0) {
+        throw new DecisionGraphError('unknown cost requires conservative price bound');
+    }
+}
+/** Embedded-host bridge: calls the same evaluateDecisionRuleset that the shipped
+ * decision-evaluate skill script wraps, in process. Use decisionEvaluateSkillFlowInvoker
+ * to run the skill's own entrypoint and request contract.
+ * Host owns authenticated artifact resolution, adapters, receipt store and price bound.
+ * The graph artifact supplies no credentials, executable adapters or permissions.
+ */
+export function decisionRulesetFlowInvoker(graph, host) {
+    assertUnknownCostBound(host);
+    return async (flow) => {
+        const { node, input } = decisionFlowNode(graph, flow);
+        const resolved = host.resolve(node.id);
+        assertDecisionFlowPins(node, resolved.binding, Object.values(resolved.definitions));
+        // The entry has no dependency: only the trusted host input is used.
+        const result = await (host.evaluate ?? evaluateDecisionRuleset)({ ...resolved,
+            input: node.id === graph.entry ? resolved.input : input,
+            runId: flow.runId, invocationId: flow.invocationKey });
+        return decisionFlowResponse(graph, node, result, host);
+    };
+}
+//# sourceMappingURL=graph-decision-bridge.js.map

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

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../security/artifact-trust.js';
+import { admitEntry } from './entry.js';
+import { DecisionGraphError, planDecisionGraph } from './graph.js';
+const digest = (value) => `sha256:${createHash('sha256').update(canonicalJson(value)).digest('hex')}`;
+const fields = ['attempts', 'deadlineMs', 'tokens', 'costMicros', 'fanOut', 'beamWidth', 'depth', 'concurrency'];
+/** Caller, workspace and provider ceilings may only narrow the graph's authored ceiling. */
+export function effectiveGraphCeilings(graph, ...ceilings) {
+    const result = { ...graph.budget };
+    for (const layer of ceilings) {
+        for (const field of fields) {
+            const limit = layer[field];
+            if (limit === undefined)
+                continue;
+            if (!Number.isSafeInteger(limit) || limit < 1)
+                throw new DecisionGraphError('invalid graph ceiling');
+            result[field] = Math.min(result[field], limit);
+        }
+    }
+    return result;
+}
+/** Audit complete immutable observations against an already validated trusted plan.
+ * No partial receipt is returned on malformed observations. Unknown cost fails closed.
+ */
+export function auditGraphEvidence(graph, plan, observations, ceilings = [], unknownCostBoundMicros) {
+    try {
+        admitEntry({ graph, plan, observations, ceilings, ...(unknownCostBoundMicros === undefined ? {} : { unknownCostBoundMicros }) });
+    }
+    catch {
+        throw new DecisionGraphError('graph evidence admission denied');
+    }
+    // Revalidate topology and reject forged plan groups/edges. This does not resolve pins;
+    // trusted pin resolution belongs to the caller that created the original plan.
+    const pins = new Set(graph.nodes.flatMap(node => [node.definition.digest, node.binding.digest]));
+    const expected = planDecisionGraph(graph, pins);
+    if (canonicalJson(plan) !== canonicalJson(expected))
+        throw new DecisionGraphError('graph/plan mismatch');
+    const limits = effectiveGraphCeilings(graph, ...ceilings);
+    const byId = new Map();
+    for (const obs of observations) {
+        if (byId.has(obs.node) || !graph.nodes.some(n => n.id === obs.node))
+            throw new DecisionGraphError('duplicate or unknown observation');
+        for (const field of ['attempts', 'tokens', 'durationMs']) {
+            if (!Number.isSafeInteger(obs[field]) || obs[field] < 0)
+                throw new DecisionGraphError('invalid usage');
+        }
+        if (obs.costMicros !== null && (!Number.isSafeInteger(obs.costMicros) || obs.costMicros < 0))
+            throw new DecisionGraphError('invalid cost');
+        if (obs.costMicros === null && (!Number.isSafeInteger(unknownCostBoundMicros) || unknownCostBoundMicros < 1))
+            throw new DecisionGraphError('unknown cost without bound');
+        if (typeof obs.used !== 'boolean' || !['ok', 'abstained', 'error', 'unsupported', 'cancelled', 'skipped'].includes(obs.status))
+            throw new DecisionGraphError('invalid observation');
+        const names = graph.nodes.find(n => n.id === obs.node).output;
+        if (!obs.output || Array.isArray(obs.output) || typeof obs.output !== 'object' ||
+            Object.keys(obs.output).some(name => !names.includes(name)))
+            throw new DecisionGraphError('undeclared observation output');
+        if (obs.status === 'skipped' && (obs.used || obs.attempts !== 0 || obs.tokens !== 0 || obs.costMicros !== 0 || obs.durationMs !== 0 || Object.keys(obs.output).length)) {
+            throw new DecisionGraphError('skipped node has resource usage');
+        }
+        byId.set(obs.node, obs);
+    }
+    const totals = { attempts: 0, tokens: 0, costMicros: 0, durationMs: 0 };
+    let outcome = 'complete';
+    const stages = plan.stages.map(stage => ({ stage: stage.stage, nodes: stage.nodes.map(id => {
+            const obs = byId.get(id);
+            if (!obs)
+                throw new DecisionGraphError('missing graph observation');
+            const input = {};
+            for (const edge of plan.edges.filter(e => e.to === id)) {
+                const source = byId.get(edge.from);
+                if (!source || source.status !== 'ok' || (!source.used && obs.used) || !Object.hasOwn(source.output, edge.source)) {
+                    // Keep the earliest explicit cause (for example an abstained predecessor).
+                    if (outcome === 'complete')
+                        outcome = 'incomplete-evidence';
+                    continue;
+                }
+                input[edge.destination] = { sourceNode: edge.from, sourceResultDigest: digest(source.output), value: source.output[edge.source] };
+            }
+            const node = graph.nodes.find(n => n.id === id);
+            if (outcome === 'complete' && obs.status !== 'skipped' && node.input.some(key => !Object.hasOwn(input, key)))
+                outcome = 'incomplete-evidence';
+            const costMicros = obs.costMicros ?? unknownCostBoundMicros;
+            totals.attempts += obs.attempts;
+            totals.tokens += obs.tokens;
+            totals.costMicros += costMicros;
+            totals.durationMs += obs.durationMs;
+            if (![totals.attempts, totals.tokens, totals.costMicros, totals.durationMs].every(Number.isSafeInteger))
+                throw new DecisionGraphError('usage overflow');
+            if (obs.status === 'cancelled')
+                outcome = 'cancelled';
+            else if (outcome === 'complete' && obs.status !== 'ok' && obs.status !== 'skipped')
+                outcome = obs.status;
+            return { id, status: obs.status, used: obs.used, input, resultDigest: digest(obs.output),
+                attempts: obs.attempts, tokens: obs.tokens, costMicros, durationMs: obs.durationMs,
+                ...(obs.flow ? { flow: obs.flow } : {}) };
+        }) }));
+    if (stages.some(stage => {
+        const stageLimit = graph.stageBudgets?.find(b => b.stage === stage.stage)?.limits;
+        if (!stageLimit)
+            return false;
+        const spent = { attempts: 0, tokens: 0, costMicros: 0, durationMs: 0 };
+        for (const node of stage.nodes) {
+            spent.attempts += node.attempts;
+            spent.tokens += node.tokens;
+            spent.costMicros += node.costMicros;
+            spent.durationMs += node.durationMs;
+        }
+        return spent.attempts > stageLimit.attempts || spent.tokens > stageLimit.tokens ||
+            spent.costMicros > stageLimit.costMicros || spent.durationMs > stageLimit.deadlineMs ||
+            stage.nodes.length > stageLimit.fanOut;
+    }))
+        outcome = 'budget-exhausted';
+    if (totals.attempts > limits.attempts || totals.tokens > limits.tokens || totals.costMicros > limits.costMicros ||
+        totals.durationMs > limits.deadlineMs || stages.length > limits.depth ||
+        stages.some(stage => stage.nodes.length > limits.fanOut))
+        outcome = 'budget-exhausted';
+    if (observations.some(obs => obs.status === 'cancelled'))
+        outcome = 'cancelled';
+    const receipt = { schemaVersion: 'decision-graph-evidence/v1', graphDigest: plan.graphDigest,
+        planDigest: plan.planDigest, limits, stages, totals, outcome };
+    return { ...receipt, receiptDigest: digest(receipt) };
+}
+//# sourceMappingURL=graph-evidence.js.map

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

@@ -0,0 +1,56 @@
+import { DecisionGraphError } from './graph.js';
+/** Attach trusted host admission to Flow's existing invokeNode seam. The estimator
+ * must bound a full decision-evaluate call including retries/fallback and unknown
+ * cost; without a conservative estimate, reject before invoking any adapter.
+ */
+export function admittedDecisionFlowAdapter(ledger, estimate, invoke, signal, onObservation) {
+    return async (request) => {
+        if (signal?.aborted) {
+            ledger.cancel();
+            throw new DecisionGraphError('graph cancelled');
+        }
+        // Flow invokes a gate only after the host approved it. The gate dispatches
+        // nothing, spends no decision budget and is not a decision observation.
+        if (request.node.kind === 'gate' && request.node.sideEffectMode === 'none' && request.node.ref === undefined) {
+            return { outputs: {}, attempts: 1, usage: { tokens: 0, costUsd: 0, timeMs: 0 } };
+        }
+        if (request.node.kind !== 'skill' || request.node.sideEffectMode !== 'none' || request.node.retry?.limit !== 0 ||
+            !/^stage-(0|[1-9]\d*)$/.test(request.node.phase ?? ''))
+            throw new DecisionGraphError('unauthorized graph Flow node');
+        const stage = Number(request.node.phase.slice(6));
+        const bound = estimate(request);
+        if (!bound || !Number.isSafeInteger(bound.tokens) || bound.tokens < 1 ||
+            !Number.isSafeInteger(bound.costMicros) || bound.costMicros < 1)
+            throw new DecisionGraphError('missing conservative graph estimate');
+        const reservation = ledger.reserve(stage, bound);
+        try {
+            const response = await invoke(request);
+            if (!response || !response.usage || !Number.isSafeInteger(response.usage.tokens) || response.usage.tokens < 0 ||
+                !Number.isFinite(response.usage.costUsd) || response.usage.costUsd < 0 ||
+                !Number.isSafeInteger(response.usage.timeMs) || response.usage.timeMs < 0 ||
+                !Number.isSafeInteger(response.attempts) || response.attempts < 1 ||
+                ![undefined, 'ok', 'abstained', 'unsupported'].includes(response.status) ||
+                (response.status !== undefined && response.status !== 'ok' && Object.keys(response.outputs ?? {}).length)) {
+                ledger.cancel();
+                throw new DecisionGraphError('invalid graph usage');
+            }
+            const micros = Math.ceil(response.usage.costUsd * 1_000_000);
+            reservation({ attempts: response.attempts, tokens: response.usage.tokens, costMicros: micros });
+            if (signal?.aborted) {
+                ledger.cancel();
+                throw new DecisionGraphError('graph cancelled');
+            }
+            onObservation?.({ request, response });
+            // Record the spent attempt, then fail the Flow node so no dependent runs.
+            if (response.status === 'abstained' || response.status === 'unsupported') {
+                throw new DecisionGraphError(`decision node ${response.status}`);
+            }
+            return response;
+        }
+        catch (error) {
+            ledger.cancel();
+            throw error;
+        }
+    };
+}
+//# sourceMappingURL=graph-flow-adapter.js.map