@agenticprimitives/orchestration 0.0.0-alpha.1 → 0.0.0-alpha.3

package/dist/loop.js

@@ -1,4 +1,22 @@
+// runIntent — the agentic loop (intent → plan → execute → observe → bounded re-plan). The capstone primitive
+// of ADR-0044: a first-party surface posts a GOAL; this loop decides + composes tools to satisfy it. Pure:
+// the planner, the tool invoker and the authority ports are injected; this module owns only the control
+// flow + fail-closed gates.
+//
+// Spec 350 §4 — for every step whose TOOL declares a capability, the loop runs the authority path BEFORE
+// invoking it, and again after any approval:
+//
+//   verify ─▶ deny              ─▶ receipt(denied) ─▶ run outcome `denied`. NO re-plan, NO fallback: a
+//          │                       denial is not a tool failure, and a planner that could route around
+//          │                       one would be an authority escalation.
+//          ├─▶ approval-required ─▶ policy adds obligations ─▶ ApprovalPort ─▶ discharged? ─▶ RE-VERIFY
+//          └─▶ allow             ─▶ policy adds obligations ─▶ (same, if any) ─▶ execute ─▶ receipt
+//
+// A step with no capability skips the path and still emits a receipt: the trace is the product, and
+// "nothing was verified" is itself a fact worth recording.
+import { compactObservations } from './artifacts.js';
 import { OrchestrationError } from './types.js';
+import { inputsFor, isInputRequired, receiptPending } from './input.js';
 /** Read a dot/index path (e.g. `list.record_types.0.record_type`) out of the ref store. A bare name with no
  *  dots is a plain top-level lookup. A missing segment short-circuits to `undefined` (the tool then validates
  *  its own args — fail-closed, no path traversal / eval). */
@@ -26,6 +44,29 @@ function resolveValue(v, refs) {
 function resolveArgs(args, refs) {
     return resolveValue(args, refs);
 }
+/** Per-item substitution for a fanned-out step: the literal `'$item'` becomes the element; an
+ *  `{ $item: 'path' }` object becomes a field of it. Applied at EXPANSION, so each expanded step's args
+ *  are concrete before normalisation, verification, or anything else reads them. */
+function substituteItem(args, item) {
+    const walk = (v) => {
+        if (v === '$item')
+            return item;
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            const o = v;
+            if (typeof o.$item === 'string') {
+                let out = item;
+                for (const seg of o.$item.split('.').filter(Boolean))
+                    out = out?.[seg];
+                return out;
+            }
+            return Object.fromEntries(Object.entries(o).map(([k, x]) => [k, walk(x)]));
+        }
+        if (Array.isArray(v))
+            return v.map(walk);
+        return v;
+    };
+    return walk(args);
+}
 /** Assert every step targets an exposed tool — fail-closed before any invocation (ADR-0013). */
 function assertKnownTools(plan, toolIds) {
     for (const step of plan.steps) {
@@ -46,68 +87,653 @@ async function callPlanner(planner, input) {
         throw new OrchestrationError('planner_failed', e instanceof Error ? e.message : String(e));
     }
 }
+/** The step joined to its tool's declaration — what the authority layer judges. Risk and capability come
+ *  from the TOOL; the plan cannot lower them. */
+function resolveStep(runRef, index, step, tool, args) {
+    const stepRef = step.id ?? `s${index}`;
+    const cap = tool.capability;
+    const risk = !cap ? 'informational' : tool.irreversible ? 'critical' : (tool.risk ?? 'low');
+    const resourceRaw = cap?.resourceArg ? args[cap.resourceArg] : undefined;
+    const authorityRaw = cap?.authorityArg ? args[cap.authorityArg] : undefined;
+    const needsKey = risk === 'medium' || risk === 'high' || risk === 'critical';
+    return {
+        runRef, stepRef, index, step, tool, args,
+        capability: cap
+            ? {
+                id: cap.id, action: cap.action,
+                ...(typeof resourceRaw === 'string' ? { resource: resourceRaw } : {}),
+                ...(typeof authorityRaw === 'string' ? { authority: authorityRaw } : {}),
+            }
+            : { id: '', action: '' },
+        risk,
+        ...(needsKey || step.idempotencyKey ? { idempotencyKey: step.idempotencyKey ?? `${runRef}:${stepRef}` } : {}),
+    };
+}
+const randomRef = () => `run-${Math.random().toString(36).slice(2, 10)}${Date.now().toString(36)}`;
+/** A stable digest is the sink's job (it has the hashing deps); here we record a cheap structural fingerprint
+ *  so two receipts for the same input compare equal. Never treated as a cryptographic commitment. */
+function fingerprint(v) {
+    try {
+        return `json:${JSON.stringify(v, (_k, x) => (typeof x === 'bigint' ? x.toString() : x))}`.slice(0, 2048);
+    }
+    catch {
+        return 'json:<unserializable>';
+    }
+}
+/** Does a declared branch hold against the results so far? Absent/empty is false for `exists`; `equals`
+ *  compares by fingerprint (the same JSON is the same value). */
+function holds(when, refs) {
+    const v = getPath(refs, when.ref);
+    if (when.equals !== undefined)
+        return fingerprint(v) === fingerprint(when.equals);
+    if (when.exists === false)
+        return v === undefined || v === null || (Array.isArray(v) && v.length === 0);
+    return !(v === undefined || v === null || (Array.isArray(v) && v.length === 0));
+}
+/** Every `name` a step's args `$ref`, by the first path segment. */
+function refsUsed(args) {
+    const out = new Set();
+    const walk = (v) => {
+        if (!v || typeof v !== 'object')
+            return;
+        if (Array.isArray(v)) {
+            v.forEach(walk);
+            return;
+        }
+        const o = v;
+        if (typeof o.$ref === 'string')
+            out.add(o.$ref.split('.')[0]);
+        Object.values(o).forEach(walk);
+    };
+    walk(args);
+    return out;
+}
+/**
+ * The indices of the batch starting at `i`: the step and the consecutive steps after it that may run
+ * beside it (spec 370 P3). A step runs beside others only when its tool exercises no capability, it fans
+ * nothing out, no `after` edge points into the batch, none of its `$ref`s (or its `when`) name a result the
+ * batch produces, and it is not a replay (a replay is instant; keeping it alone keeps the order obvious).
+ */
+function independentBatch(plan, i, toolsById, completed) {
+    const concurrent = (j) => {
+        const st = plan.steps[j];
+        const t = toolsById.get(st.toolId);
+        return !!t && !t.capability && !st.forEach && !completed.has(st.id ?? `s${j}`);
+    };
+    const batch = [i];
+    if (!concurrent(i))
+        return batch;
+    const first = plan.steps[i];
+    const produced = new Set(first.ref ? [first.ref] : []);
+    const ids = new Set([first.id ?? `s${i}`]);
+    for (let j = i + 1; j < plan.steps.length; j++) {
+        const st = plan.steps[j];
+        if (!concurrent(j))
+            break;
+        if (st.after?.some((id) => ids.has(id)))
+            break;
+        if ([...refsUsed(st.args)].some((r) => produced.has(r)))
+            break;
+        if (st.when && produced.has(st.when.ref.split('.')[0]))
+            break;
+        batch.push(j);
+        if (st.ref)
+            produced.add(st.ref);
+        ids.add(st.id ?? `s${j}`);
+    }
+    return batch;
+}
 /**
  * Run an intent to a terminal result. Plans, executes the steps in order (threading `ref` results into later
  * args), observes, and re-plans (bounded) when a step throws. Returns `completed` with the last successful
- * step's result, or `failed` with the error. Fail-closed throughout: an unknown tool, an empty plan, no plan,
- * or an exhausted step budget all produce a `failed` RunResult (never a misleading empty success).
+ * step's result, `failed` with the error, `denied` when authority refused a step, or `suspended` when an
+ * approval is pending. Fail-closed throughout: an unknown tool, an empty plan, no plan, an exhausted step
+ * budget, a capability step with no verifier, or a denial all produce a non-completed RunResult — never a
+ * misleading empty success.
  */
 export async function runIntent(intent, opts) {
-    const maxSteps = opts.maxSteps ?? 8;
+    // THE STEP BUDGET bounds what a PLANNER may keep proposing (a re-plan loop that never ends), not what a
+    // declared fan-out enumerates: that is capped by the ontology's binding (spec 358 W4 `maxItems`) at the
+    // point of expansion, and an expansion of N items widens the budget by N − 1 so "ask each of nine
+    // members" is not refused for being nine (spec 380).
+    let maxSteps = opts.maxSteps ?? 8;
     const maxReplans = opts.maxReplans ?? 1;
-    const toolIds = new Set(opts.tools.map((t) => t.id));
+    const runRef = opts.runRef ?? randomRef();
+    const now = opts.now ?? (() => Math.floor(Date.now() / 1000));
+    const ports = opts.ports ?? {};
+    const presentedAll = opts.presented == null ? [] : Array.isArray(opts.presented) ? opts.presented : [opts.presented];
+    if (presentedAll.length > 1 && !opts.selectPresentation) {
+        throw new OrchestrationError('keyring_needs_selector', 'several mandates were presented and no selectPresentation was provided — the loop does not guess which authority a step spends');
+    }
+    const toolsById = new Map(opts.tools.map((t) => [t.id, t]));
+    const toolIds = new Set(toolsById.keys());
     const allObservations = [];
+    const receipts = [];
+    /** Executed steps whose tool declares a compensation, newest first — unwound on failure. */
+    const compensable = [];
     const refs = {};
     let executed = 0;
     let replans = 0;
     let lastResult;
+    // Spec 390 W3 — every event is stamped as it leaves, so a record can be read back as a timeline.
+    const sink = ports.events;
+    const emit = (e) => { sink?.({ ...e, at: Date.now() }); };
+    const record = async (r) => {
+        // The playbook shaped the whole run (it selected the tools + instructions at admission), so every
+        // step it produced cites the same skillRef. Stamped at the one chokepoint every receipt passes.
+        if (opts.skillRef && r.skillRef === undefined)
+            r.skillRef = opts.skillRef;
+        receipts.push(r);
+        emit({ type: 'ReceiptCreated', runRef, stepRef: r.stepRef, status: r.status });
+        if (ports.receiptSink)
+            await ports.receiptSink.record(r);
+    };
+    const base = (rs, startedAt) => ({
+        runRef, stepRef: rs.stepRef, index: rs.index, toolId: rs.tool.id, risk: rs.risk, startedAt,
+        ...(rs.risk !== 'informational' ? { capability: rs.capability } : {}),
+        ...(rs.idempotencyKey ? { idempotencyKey: rs.idempotencyKey } : {}),
+        inputDigest: fingerprint(rs.args),
+        // Spec 367 §5 — the binding the step was admitted under, pinned by the harness that knows the
+        // intent, the principal and where each argument came from. Recorded on every receipt of the step.
+        ...(() => { const b = opts.bindingFor?.(rs); return b ? { binding: b } : {}; })(),
+    });
+    /** The one mandate THIS step is judged under (spec 358 W4 keyring). Null = none fits this step, which
+     *  the caller turns into authority-required for THIS step's args — never a denial borrowed from a
+     *  mandate meant for a different item. The selector runs whenever it is provided AND anything is
+     *  presented, INCLUDING a single mandate: a lone key that does not name this payee must ask for the
+     *  right one, not be judged and denied under the wrong one. */
+    const presentedFor = (rs) => presentedAll.length === 0
+        ? null
+        : opts.selectPresentation
+            ? opts.selectPresentation(rs, presentedAll)
+            : presentedAll[0];
+    /** The authority path for one step. Returns the decision to execute under, or a terminal RunResult. */
+    async function authorize(rs, startedAt, plan) {
+        if (!ports.mandateVerifier)
+            throw new OrchestrationError('no_authority_port', `step ${rs.stepRef} exercises ${rs.capability.id} and no MandateVerifier is configured`);
+        // Spec 358 W4 — the keyring: with several mandates presented, the selector names the one THIS step is
+        // judged under. Selection is by declared fit (payee, resource); the verifier then judges that one
+        // alone. A step no key fits reports authority-required for ITS OWN args — never a denial borrowed
+        // from a mandate that was meant for a different item.
+        const presented = presentedFor(rs);
+        if (!presented) {
+            if (opts.onMissingMandate !== 'report')
+                throw new OrchestrationError('no_mandate_presented', `step ${rs.stepRef} exercises ${rs.capability.id} and the caller presented no mandate`);
+            // 401, not 403. Nothing was verified and nothing ran; the receipt records that the plan reached a
+            // step it had no authority for, and the caller is told WHICH step so it can go and get one.
+            emit({ type: 'RunSuspended', runRef, stepRef: rs.stepRef, resumeToken: rs.stepRef });
+            await record({ ...base(rs, startedAt), status: 'authority-required', completedAt: now() });
+            return {
+                outcome: 'authority-required', plan, steps: allObservations, receipts, runRef,
+                required: { stepRef: rs.stepRef, toolId: rs.tool.id, capability: rs.capability, risk: rs.risk, args: rs.args },
+            };
+        }
+        const req = { intent, presented, step: rs, afterApproval: false };
+        let decision = await ports.mandateVerifier.verify(req);
+        emit({ type: 'MandateChecked', runRef, stepRef: rs.stepRef, decision: decision.decision, afterApproval: false });
+        if (decision.decision === 'deny') {
+            emit({ type: 'MandateDenied', runRef, stepRef: rs.stepRef, reasons: decision.reasons });
+            await record({ ...base(rs, startedAt), status: 'denied', authority: { presentedRef: presented.ref, decision, afterApproval: false }, completedAt: now(), error: decision.reasons.map((r) => `${r.code}: ${r.message}`).join('; ') });
+            return { outcome: 'denied', plan, steps: allObservations, receipts, runRef, error: decision.reasons.map((r) => `${r.code}: ${r.message}`).join('; ') };
+        }
+        // Obligations: the verifier's, plus whatever policy adds for this risk class. Never fewer.
+        let obligations = [...decision.obligations];
+        if (ports.policyEvaluator) {
+            const extra = await ports.policyEvaluator.evaluate({ ...req, decision });
+            obligations = [...obligations, ...extra.obligations];
+        }
+        let approvalRecords = [];
+        if (obligations.length > 0) {
+            if (!ports.approvalPort)
+                throw new OrchestrationError('no_approval_port', `step ${rs.stepRef} carries ${obligations.length} obligation(s) and no ApprovalPort is configured`);
+            emit({ type: 'ApprovalRequested', runRef, stepRef: rs.stepRef, obligations });
+            const outcome = await ports.approvalPort.request({ runRef, stepRef: rs.stepRef, intent, step: rs, obligations, evidence: decision.evidence });
+            if (outcome.status === 'pending') {
+                emit({ type: 'RunSuspended', runRef, stepRef: rs.stepRef, resumeToken: outcome.resumeToken });
+                const prompt = outcome.prompt ? { ...outcome.prompt, stepRef: rs.stepRef, toolId: rs.tool.id } : undefined;
+                await record({
+                    ...base(rs, startedAt), status: 'suspended',
+                    authority: { presentedRef: presented.ref, decision, afterApproval: false },
+                    ...(prompt ? { pendingInput: receiptPending(prompt) } : {}),
+                    completedAt: now(),
+                });
+                return { outcome: 'suspended', plan, steps: allObservations, receipts, runRef, resumeToken: outcome.resumeToken, ...(prompt ? { prompt } : {}) };
+            }
+            if (outcome.status === 'refused') {
+                emit({ type: 'ApprovalRefused', runRef, stepRef: rs.stepRef, ...(outcome.reason ? { reason: outcome.reason } : {}) });
+                const error = `approval refused${outcome.by ? ` by ${outcome.by}` : ''}${outcome.reason ? `: ${outcome.reason}` : ''}`;
+                await record({ ...base(rs, startedAt), status: 'denied', authority: { presentedRef: presented.ref, decision, afterApproval: false }, completedAt: now(), error });
+                return { outcome: 'denied', plan, steps: allObservations, receipts, runRef, error };
+            }
+            approvalRecords = outcome.records;
+            emit({ type: 'ApprovalDischarged', runRef, stepRef: rs.stepRef, records: approvalRecords });
+            // RE-VERIFY. An approval is an input to the verifier, not a bypass of it: the mandate may have been
+            // revoked while the approver was deciding.
+            decision = await ports.mandateVerifier.verify({ ...req, afterApproval: true });
+            emit({ type: 'MandateChecked', runRef, stepRef: rs.stepRef, decision: decision.decision, afterApproval: true });
+            if (decision.decision !== 'allow') {
+                const reasons = decision.decision === 'deny' ? decision.reasons : [{ code: 'still-obligated', message: 'obligations remain after approval' }];
+                emit({ type: 'MandateDenied', runRef, stepRef: rs.stepRef, reasons });
+                const error = reasons.map((r) => `${r.code}: ${r.message}`).join('; ');
+                await record({ ...base(rs, startedAt), status: 'denied', authority: { presentedRef: presented.ref, decision, afterApproval: true }, approvalRecords, completedAt: now(), error });
+                return { outcome: 'denied', plan, steps: allObservations, receipts, runRef, error };
+            }
+        }
+        return { decision, approvalRecords, used: presented };
+    }
+    /** Unwind executed steps that declared compensation, newest first. Best effort: a compensation that
+     *  fails is recorded, not retried — the receipt is the honest record. Compensations are AUTHORIZED
+     *  like any other capability step; a denied compensation is recorded as such. */
+    async function compensate() {
+        for (const { resolved, result } of compensable.reverse()) {
+            const comp = resolved.tool.compensation;
+            const compTool = toolsById.get(comp.toolId);
+            const startedAt = now();
+            const args = resolveValue(comp.args, { ...refs, $result: result });
+            const crs = compTool
+                ? resolveStep(runRef, resolved.index, { toolId: comp.toolId, args, id: `${resolved.stepRef}:compensate` }, compTool, args)
+                : { ...resolved, stepRef: `${resolved.stepRef}:compensate`, tool: { id: comp.toolId, description: '' }, args, risk: 'informational', capability: { id: '', action: '' } };
+            let ok = false;
+            let error;
+            try {
+                const compPresented = presentedFor(crs);
+                if (crs.risk !== 'informational' && ports.mandateVerifier && compPresented) {
+                    const d = await ports.mandateVerifier.verify({ intent, presented: compPresented, step: crs, afterApproval: false });
+                    if (d.decision !== 'allow') {
+                        error = `compensation not authorized: ${d.decision}`;
+                    }
+                }
+                if (!error) {
+                    await opts.invoke(comp.toolId, args, { intent, step: crs.step, index: crs.index, ...(crs.idempotencyKey ? { idempotencyKey: crs.idempotencyKey } : {}) });
+                    ok = true;
+                }
+            }
+            catch (e) {
+                error = e instanceof Error ? e.message : String(e);
+            }
+            emit({ type: 'StepCompensated', runRef, stepRef: resolved.stepRef, by: comp.toolId, ok });
+            await record({ ...base(crs, startedAt), status: ok ? 'compensated' : 'failed', completedAt: now(), ...(error ? { error } : {}) });
+        }
+        compensable.length = 0;
+    }
+    emit({ type: 'RunStarted', runRef, intent, presentedRef: presentedAll[0]?.ref ?? null });
+    let plan = { steps: [] };
+    const completedByRef = new Map((opts.resume?.completed ?? []).map((c) => [c.stepRef, c]));
     try {
-        let plan = await callPlanner(opts.planner, { intent, tools: opts.tools });
+        plan = opts.resume ? { ...opts.resume.plan, steps: [...opts.resume.plan.steps] } : await callPlanner(opts.planner, { intent, tools: opts.tools });
         assertKnownTools(plan, toolIds);
-        // The plan loop: walk the current plan; on a step failure, re-plan (bounded) and restart with a fresh plan.
+        // ── PLAN ADMISSION (spec 367 W1) — is this the plan the sentence asked for? Deterministic, reads the
+        // tools' declarations; refused ⇒ ONE re-plan told exactly what was wrong; refused again ⇒ denied, with
+        // the violations as the answer. Nothing has run at this point, so a denial here costs nobody anything
+        // but a wrong act they did not get.
+        if (ports.planAdmission) {
+            let verdict = await ports.planAdmission.admit({ intent, plan, tools: opts.tools });
+            // A PLACEHOLDER IS AN UNANSWERED QUESTION, NOT A REFUSAL. A violation whose recovery is `ask` names
+            // an argument the planner could not fill ("<UNKNOWN>" for the amount); dropping that argument turns
+            // it into one the step declares and lacks — which §3.5 then ASKS the person for. Refusing instead,
+            // twice, put the placeholder itself into the refusal a person read ("send money to bob" → a wall of
+            // <UNKNOWN>), when "how much?" was the whole answer.
+            if (!verdict.admitted && verdict.violations.every((v) => v.recovery === 'ask' && v.stepIndex !== undefined && v.field)) {
+                const asked = verdict.violations.map((v) => `${v.stepIndex}:${v.field}`);
+                plan = { ...plan, steps: plan.steps.map((st, i) => {
+                        const drop = verdict.admitted ? [] : verdict.violations.filter((v) => v.stepIndex === i).map((v) => v.field);
+                        if (!drop.length)
+                            return st;
+                        const args = { ...st.args };
+                        for (const k of drop)
+                            delete args[k];
+                        return { ...st, args };
+                    }) };
+                emit({ type: 'PlanRefused', runRef, violations: verdict.violations, replanning: false });
+                verdict = await ports.planAdmission.admit({ intent, plan, tools: opts.tools });
+                if (verdict.admitted)
+                    emit({ type: 'PlanCreated', runRef, steps: plan.steps.length, rationale: `placeholders dropped to be asked for: ${asked.join(', ')}` });
+            }
+            // A REFUSAL IS TERMINAL (spec 379). A violation whose recovery is `refuse` names something no re-plan
+            // may cure by leaving it out: a value-moving step aimed at an outside agent, re-planned without the
+            // executor, would be this harness quietly doing what the person asked another to do. Denied as asked.
+            if (!verdict.admitted && verdict.violations.some((v) => v.recovery === 'refuse')) {
+                emit({ type: 'PlanRefused', runRef, violations: verdict.violations, replanning: false });
+                const error = `plan_refused: ${verdict.violations.map((v) => v.message).join(' | ')}`;
+                return { outcome: 'denied', plan, steps: allObservations, receipts, runRef, error };
+            }
+            if (!verdict.admitted) {
+                emit({ type: 'PlanRefused', runRef, violations: verdict.violations, replanning: true });
+                const told = { ...intent, context: { ...(intent.context ?? {}), admission: verdict.violations.map((v) => v.message) } };
+                plan = await callPlanner(opts.planner, { intent: told, tools: opts.tools });
+                assertKnownTools(plan, toolIds);
+                verdict = await ports.planAdmission.admit({ intent, plan, tools: opts.tools });
+                if (!verdict.admitted) {
+                    emit({ type: 'PlanRefused', runRef, violations: verdict.violations, replanning: false });
+                    const error = `plan_refused: ${verdict.violations.map((v) => v.message).join(' | ')}`;
+                    return { outcome: 'denied', plan, steps: allObservations, receipts, runRef, error };
+                }
+            }
+        }
+        emit({ type: 'PlanCreated', runRef, steps: plan.steps.length, ...(plan.rationale ? { rationale: plan.rationale } : {}) });
+        const attempt = async (i, step) => {
+            const tool = toolsById.get(step.toolId);
+            // ── ALREADY RAN (spec 370 P1) — replayed as evidence, never as permission. ────────────────
+            // A resume used to re-execute every completed step: a planner call, every read again, and a
+            // correctness that rested on each invoker noticing its own earlier act. The recorded outcome
+            // stands in for it here; the invoker and the verifier are not called because nothing is being
+            // attempted. The steps that follow are judged as if for the first time.
+            const done = completedByRef.get(step.id ?? `s${i}`);
+            if (done) {
+                const stepRef = step.id ?? `s${i}`;
+                const obs = { step, ok: true, result: done.result, stepRef, replayed: true };
+                if (step.ref)
+                    refs[step.ref] = done.result;
+                if (done.receipt)
+                    receipts.push(done.receipt);
+                emit({ type: 'StepReplayed', runRef, stepRef, toolId: step.toolId });
+                return { kind: 'done', obs };
+            }
+            // ── A DECLARED BRANCH (spec 370 P3) — taken or not by a prior result, never by a second plan. ──
+            if (step.when && !holds(step.when, refs)) {
+                const stepRef = step.id ?? `s${i}`;
+                const rs = resolveStep(runRef, i, step, tool, resolveArgs(step.args, refs));
+                const because = `${step.when.ref} ${step.when.equals !== undefined ? `≠ ${fingerprint(step.when.equals)}` : 'is absent'}`;
+                emit({ type: 'StepSkipped', runRef, stepRef, toolId: tool.id, because });
+                await record({ ...base(rs, now()), status: 'skipped', completedAt: now(), error: `not taken: ${because}` });
+                return { kind: 'done', obs: { step, ok: true, stepRef, skipped: true } };
+            }
+            let args = resolveArgs(step.args, refs);
+            // ── ANSWERS THE PERSON ALREADY GAVE ARE PART OF THIS STEP'S ARGUMENTS ──────────────────────
+            // A `data` question raised while NORMALISING (§3.5) — "which Nathan do you mean?" — is answered
+            // against the step, not against a tool that has not run yet. Without this the answer travelled in
+            // `ctx.supplied`, which only an invoker ever reads, so normalisation re-ran on the planner's
+            // original words and asked the identical question forever. Every disambiguation was unanswerable.
+            //
+            // Only names the TOOL declares are accepted: `supplied` arrives from a client, and a question we
+            // asked is not a licence to set arguments we did not ask about.
+            const declaredArgs = tool.inputSchema?.properties;
+            for (const answer of inputsFor(opts.supplied, step.id ?? `s${i}`)) {
+                for (const [name, value] of Object.entries(answer.data ?? {})) {
+                    if (value === undefined || value === '')
+                        continue;
+                    if (declaredArgs && !(name in declaredArgs))
+                        continue;
+                    args = { ...args, [name]: value };
+                }
+            }
+            const startedAt = now();
+            if (opts.normalizeArgs) {
+                // Normalisation may not be able to finish alone: "send it to alice" names a person the substrate
+                // has to identify, and there may be several Alices or none. That is a QUESTION, not a failure —
+                // the same suspension a tool raises, from the one place that turns words into canonical values.
+                // Guessing a counterparty would be the worst possible way to be helpful.
+                try {
+                    args = await opts.normalizeArgs({ toolId: step.toolId, tool, args });
+                    if (opts.resolveExecutor && typeof step.executor === 'string' && step.executor.trim()) {
+                        const executor = await opts.resolveExecutor({ step, tool });
+                        const { executor: _named, ...rest } = step;
+                        step = executor ? { ...rest, executor } : rest;
+                    }
+                }
+                catch (e) {
+                    if (!isInputRequired(e))
+                        throw e;
+                    const pending = resolveStep(runRef, i, step, tool, args);
+                    const request = { ...e.request, stepRef: pending.stepRef, toolId: tool.id };
+                    emit({ type: 'RunSuspended', runRef, stepRef: pending.stepRef, resumeToken: pending.stepRef });
+                    await record({ ...base(pending, startedAt), status: 'suspended', pendingInput: receiptPending(request), completedAt: now() });
+                    return { kind: 'exit', result: { outcome: 'suspended', plan, steps: allObservations, receipts, runRef, resumeToken: pending.stepRef, prompt: request }, compensate: false };
+                }
+            }
+            const rs = resolveStep(runRef, i, step, tool, args);
+            emit({ type: 'StepProposed', runRef, stepRef: rs.stepRef, toolId: tool.id, risk: rs.risk });
+            // ── authority, for every step that exercises a capability ──
+            let authority;
+            let approvalRecords = [];
+            // Spec 374 §1 — THE ASK IS ROUTED; THE MANDATE IS NOT. A step whose subject is another agent is
+            // sent there (spec 366 R1), and THAT agent judges its authority under its own playbook, asks its own
+            // steward, and answers. Judging it here would ask the asker for a mandate the subject never
+            // delegated to them — which is what happened when this branch did not exist: a member was asked
+            // for the organization's mandate before the step ever left. Recorded as routed, never as allowed:
+            // this run holds only what the subject answers, and its receipt says so.
+            const judgedAt = rs.risk !== 'informational' && opts.authorityJudgedElsewhere ? opts.authorityJudgedElsewhere(rs) : null;
+            if (judgedAt) {
+                authority = {
+                    presentedRef: 'routed',
+                    decision: {
+                        decision: 'allow', obligations: [],
+                        evidence: { mandateRef: `routed:${judgedAt}`, intentDigest: fingerprint(intent), evaluatedAt: now(), verdicts: [{ enforcer: 'routed', allowed: true, reason: `the step's subject is ${judgedAt}; its authority is judged at that agent, under its own playbook and its own steward — this run holds only what it answers` }] },
+                    },
+                    afterApproval: false,
+                };
+            }
+            else if (rs.risk !== 'informational' && tool.selfAuthorized) {
+                // SELF-ACTING (see `ToolSpec.selfAuthorized`): the actor, the owner and the beneficiary are one
+                // principal, so the session is the authority and there is no second party to ask. It is still a
+                // WRITE and still gets a receipt — recorded as authorized by `self`, so a reader can tell an act
+                // backed by a session from one backed by a signature without inferring it from a missing field.
+                authority = {
+                    // `self`, not null: null is what an informational step records, and this one WROTE.
+                    presentedRef: 'self',
+                    decision: {
+                        decision: 'allow', obligations: [],
+                        // The evidence names the basis honestly — there is no mandate to reference, and inventing a
+                        // mandateRef would make a receipt claim a signature that never happened.
+                        evidence: { mandateRef: 'self', intentDigest: fingerprint(intent), evaluatedAt: now(), verdicts: [{ enforcer: 'self', allowed: true, reason: 'the run\'s own principal owns what this touches; the session is the authority' }] },
+                    },
+                    afterApproval: false,
+                };
+            }
+            else if (rs.risk !== 'informational') {
+                const a = await authorize(rs, startedAt, plan);
+                if ('outcome' in a)
+                    return { kind: 'exit', result: a, compensate: true };
+                authority = { presentedRef: a.used.ref, decision: a.decision, afterApproval: a.approvalRecords.length > 0 };
+                approvalRecords = a.approvalRecords;
+            }
+            // ── execute ──
+            const suppliedHere = inputsFor(opts.supplied, rs.stepRef);
+            const ctx = { intent, step, index: i, ...(rs.idempotencyKey ? { idempotencyKey: rs.idempotencyKey } : {}), ...(suppliedHere.length ? { supplied: suppliedHere } : {}) };
+            executed++;
+            let obs;
+            try {
+                const result = await opts.invoke(step.toolId, args, ctx);
+                obs = { step, ok: true, result, stepRef: rs.stepRef };
+                if (step.ref)
+                    refs[step.ref] = result;
+                lastResult = result;
+                if (tool.compensation && rs.risk !== 'informational')
+                    compensable.push({ resolved: rs, result });
+            }
+            catch (e) {
+                if (isInputRequired(e)) {
+                    // The tool asked the person for something (spec 350 §3.4). Not a failure — nothing is re-planned
+                    // around a question — and not a denial: authority was verified and stands. The run suspends with
+                    // the prompt; the resume re-runs the intent with the answers, through every gate again. Steps
+                    // already executed are NOT compensated: they stand, and the resume re-invokes them idempotently.
+                    const request = { ...e.request, stepRef: rs.stepRef, toolId: tool.id };
+                    emit({ type: 'RunSuspended', runRef, stepRef: rs.stepRef, resumeToken: rs.stepRef });
+                    await record({
+                        ...base(rs, startedAt),
+                        status: 'suspended',
+                        ...(authority ? { authority } : {}),
+                        ...(approvalRecords.length ? { approvalRecords } : {}),
+                        pendingInput: receiptPending(request),
+                        completedAt: now(),
+                    });
+                    return { kind: 'exit', result: { outcome: 'suspended', plan, steps: allObservations, receipts, runRef, resumeToken: rs.stepRef, prompt: request }, compensate: false };
+                }
+                obs = { step, ok: false, error: e instanceof Error ? e.message : String(e), stepRef: rs.stepRef };
+            }
+            emit({ type: 'ToolInvoked', runRef, stepRef: rs.stepRef, toolId: tool.id, ok: obs.ok });
+            const decisions = opts.decisionsFor?.(tool.id, args) ?? [];
+            const stepReceipt = {
+                ...base(rs, startedAt),
+                status: obs.ok ? 'executed' : 'failed',
+                // What was decided FOR the person on the way here, and on what basis (spec 363 W6).
+                ...(decisions.length ? { decisions: [...decisions] } : {}),
+                ...(authority ? { authority } : {}),
+                ...(approvalRecords.length ? { approvalRecords } : {}),
+                ...(obs.ok ? { outputDigest: fingerprint(obs.result) } : { error: obs.error }),
+                completedAt: now(),
+            };
+            await record(stepReceipt);
+            // ── DECLARED EFFECTS — spec 360. What the playbook promised FOLLOWS this act.
+            //
+            // Only on success: you do not tell someone about a payment that did not happen, and an effect is
+            // never a way to reach a party before authority exists.
+            //
+            // ISOLATED, ALWAYS. The step already happened, possibly on chain. A receipt that could un-do a
+            // payment would be worse than no receipt — so a throw here is caught and emitted as its own fact.
+            // The step stays `executed`; failing to disclose and failing to pay are different failures and a
+            // caller that cannot tell them apart will report a transfer as lost that actually settled.
+            if (obs.ok && ports.effectSink && opts.declaredEffects) {
+                // `resolveStep` gives a tool with no capability `{ id: '', action: '' }` rather than undefined,
+                // so this is `||` and not `??`: an informational step's effects are keyed by its TOOL id.
+                const capabilityId = rs.capability.id || tool.id;
+                try {
+                    // Resolving is part of the effect path, so a resolver that throws is the same kind of event
+                    // as a discharge that throws: reported, never fatal to an act that already happened.
+                    const declared = typeof opts.declaredEffects === 'function'
+                        ? await opts.declaredEffects(capabilityId, rs)
+                        : (opts.declaredEffects[capabilityId] ?? []);
+                    const effectOutcomes = [];
+                    for (const effect of declared ?? []) {
+                        const produces = String(effect.produces ?? '');
+                        try {
+                            await ports.effectSink.discharge({ runRef, stepRef: rs.stepRef, effect, step: rs, result: obs.result, receipt: stepReceipt });
+                            effectOutcomes.push({ produces, ok: true });
+                        }
+                        catch (e) {
+                            const error = e instanceof Error ? e.message : String(e);
+                            effectOutcomes.push({ produces, ok: false, error });
+                            emit({ type: 'EffectFailed', runRef, stepRef: rs.stepRef, error });
+                        }
+                    }
+                    // ON THE RECEIPT, not only in the event stream: "the payment stood but the payee was not
+                    // told" is evidence a caller must be able to SEE (memory: evidence before diagnosis) — an
+                    // invisible EffectFailed left every silent-delivery bug looking like success.
+                    if (effectOutcomes.length)
+                        stepReceipt.effects = effectOutcomes;
+                }
+                catch (e) {
+                    emit({ type: 'EffectFailed', runRef, stepRef: rs.stepRef, error: `could not resolve declared effects: ${e instanceof Error ? e.message : String(e)}` });
+                }
+            }
+            return { kind: 'done', obs };
+        };
         for (;;) {
             let failedMidPlan = false;
-            for (let i = 0; i < plan.steps.length; i++) {
+            for (let i = 0; i < plan.steps.length;) {
                 if (executed >= maxSteps)
                     throw new OrchestrationError('max_steps', `step budget of ${maxSteps} exhausted`);
-                const step = plan.steps[i];
-                const ctx = { intent, step, index: i };
-                const args = resolveArgs(step.args, refs);
-                executed++;
-                let obs;
-                try {
-                    const result = await opts.invoke(step.toolId, args, ctx);
-                    obs = { step, ok: true, result };
-                    if (step.ref)
-                        refs[step.ref] = result;
-                    lastResult = result;
+                let step = plan.steps[i];
+                // ── FAN-OUT — spec 358 W4. One planned step over an enumerated set becomes N ordinary steps,
+                // spliced in place, each with its own id, its own receipt, its own idempotency key, and its own
+                // pass through the verifier below: a mandate per item, never one verdict stretched over N.
+                //
+                // Fail-closed three ways, each named: the PRODUCING tool must declare which relation its result
+                // enumerates (an array being array-shaped says nothing — a search page is not a payee list); the
+                // relation must be bound fan-out-able by the injected ontology policy; and the item count must
+                // fit the binding's cap, because "every member" of a 25-person org is a plan and of a 10,000-row
+                // result it is an incident.
+                if (step.forEach) {
+                    const [refName, ...path] = step.forEach.ref.split('.');
+                    const producer = plan.steps.find((p) => p.ref === refName);
+                    const producerTool = producer ? toolsById.get(producer.toolId) : undefined;
+                    const relation = producerTool?.enumerates?.relation;
+                    if (!relation) {
+                        throw new OrchestrationError('fan_out_unbound', `forEach over "${step.forEach.ref}": the producing tool ${producerTool?.id ?? '(unknown)'} does not declare what its result enumerates`);
+                    }
+                    const binding = opts.fanOut?.(relation) ?? null;
+                    if (!binding) {
+                        throw new OrchestrationError('fan_out_unbound', `forEach over relation <${relation}> is not bound fan-out-able — the ontology's plan-shapes binding decides, and absence fails closed`);
+                    }
+                    let items = refs[refName];
+                    // A PRODUCER THAT WAS REFUSED has no set to fan out over, and the reason is the producer's refusal,
+                    // not the shape of what it returned: "Missio Nexus refused: no standing" is the answer a stranger
+                    // gets; "resolved to nothing, not an array" was what they got before this line (spec 380).
+                    const producerRefusal = items && typeof items === 'object' && typeof items.refused === 'string' ? items.refused : null;
+                    if (producerRefusal)
+                        throw new OrchestrationError('fan_out_refused', `forEach over "${step.forEach.ref}": the step that enumerates it was refused — ${producerRefusal}`);
+                    for (const seg of path)
+                        items = items?.[seg];
+                    if (!Array.isArray(items)) {
+                        throw new OrchestrationError('fan_out_not_array', `forEach ref "${step.forEach.ref}" resolved to ${items === undefined ? 'nothing' : typeof items}, not an array`);
+                    }
+                    if (items.length > binding.maxItems) {
+                        throw new OrchestrationError('fan_out_over_limit', `forEach over <${relation}> names ${items.length} items; the binding allows ${binding.maxItems}`);
+                    }
+                    const baseId = step.id ?? `s${i}`;
+                    const expanded = items.map((item, k) => ({
+                        toolId: step.toolId,
+                        args: substituteItem(step.args, item),
+                        id: `${baseId}#${k + 1}`,
+                    }));
+                    emit({ type: 'PlanCreated', runRef, steps: expanded.length, rationale: `fan-out of ${baseId} over <${relation}> into ${expanded.length} steps` });
+                    maxSteps += Math.max(0, expanded.length - 1);
+                    plan = { ...plan, steps: [...plan.steps.slice(0, i), ...expanded, ...plan.steps.slice(i + 1)] };
+                    if (expanded.length === 0)
+                        continue; // an empty set fans out to nothing, which is a fine answer (the step is gone; `i` now names the next)
+                    step = plan.steps[i];
                 }
-                catch (e) {
-                    obs = { step, ok: false, error: e instanceof Error ? e.message : String(e) };
+                // ── THE BATCH (spec 370 P3): this step and the consecutive INDEPENDENT read-only steps after it. ──
+                // Independent = no `after` edge into the batch, no `$ref` into a result the batch produces, no branch
+                // on one. Read-only = the tool exercises no capability: a step that spends authority runs alone,
+                // both because one verdict is one step's and because two userOps from one account race on its
+                // nonce. The DO is single-threaded and the steps are I/O-bound, so this is real wall-clock, safely.
+                const batch = independentBatch(plan, i, toolsById, completedByRef);
+                if (executed + batch.length > maxSteps)
+                    throw new OrchestrationError('max_steps', `step budget of ${maxSteps} exhausted`);
+                const outcomes = batch.length === 1
+                    ? [await attempt(i, step)]
+                    : await Promise.all(batch.map((j) => attempt(j, plan.steps[j])));
+                // Receipts land in completion order inside a batch; the record is read by index.
+                if (batch.length > 1)
+                    receipts.sort((a, b) => a.index - b.index || (a.stepRef.endsWith(':compensate') ? 1 : 0));
+                // What completed is recorded first, in plan order — a checkpoint taken now carries it — then the
+                // earliest exit (a question, a denial, a missing mandate) is the run's answer.
+                let exit;
+                for (const o of outcomes) {
+                    if (o.kind === 'done') {
+                        allObservations.push(o.obs);
+                        opts.onObserve?.(o.obs);
+                        if (o.obs.ok && !o.obs.skipped)
+                            lastResult = o.obs.result;
+                        if (!o.obs.ok)
+                            failedMidPlan = true;
+                    }
+                    else if (!exit)
+                        exit = o;
                 }
-                allObservations.push(obs);
-                opts.onObserve?.(obs);
-                if (!obs.ok) {
-                    failedMidPlan = true;
-                    break; // stop this plan; decide whether to re-plan below
+                if (exit) {
+                    if (exit.compensate)
+                        await compensate();
+                    return exit.result;
                 }
+                if (failedMidPlan)
+                    break; // stop this plan; decide whether to re-plan below
+                i += batch.length;
             }
             if (!failedMidPlan) {
-                return { outcome: 'completed', plan, steps: allObservations, result: lastResult };
+                emit({ type: 'RunCompleted', runRef });
+                return { outcome: 'completed', plan, steps: allObservations, receipts, runRef, result: lastResult };
             }
             if (replans >= maxReplans) {
                 const last = allObservations[allObservations.length - 1];
-                return { outcome: 'failed', plan, steps: allObservations, error: last?.error ?? 'step failed' };
+                await compensate();
+                const error = last?.error ?? 'step failed';
+                emit({ type: 'RunFailed', runRef, error });
+                return { outcome: 'failed', plan, steps: allObservations, receipts, runRef, error };
             }
             replans++;
-            plan = await callPlanner(opts.planner, { intent, tools: opts.tools, observations: allObservations });
+            // Spec 391 W2 — the planner sees what each prior step WAS and how big, not a 40 KB body in its prompt.
+            plan = await callPlanner(opts.planner, { intent, tools: opts.tools, observations: compactObservations(allObservations) });
             assertKnownTools(plan, toolIds);
+            emit({ type: 'PlanCreated', runRef, steps: plan.steps.length, ...(plan.rationale ? { rationale: plan.rationale } : {}) });
         }
     }
     catch (e) {
         const error = e instanceof OrchestrationError ? `${e.code}: ${e.message}` : e instanceof Error ? e.message : String(e);
-        // No plan was ever produced if allObservations is empty + we threw before the loop.
-        return { outcome: 'failed', plan: { steps: [] }, steps: allObservations, error };
+        await compensate();
+        emit({ type: 'RunFailed', runRef, error });
+        return { outcome: 'failed', plan, steps: allObservations, receipts, runRef, error };
     }
 }
 //# sourceMappingURL=loop.js.map