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

package/dist/spans.js

@@ -0,0 +1,589 @@
+// THE RUN, EXPORTED — spec 381 (appendix N3, the open half of P6).
+//
+// Two projections of one record, both pure, both firewalled:
+//
+//   · SPANS — the run as a trace a tool like Jaeger, Honeycomb or an OTEL collector reads: one root span per
+//     run (`invoke_agent`), one child per step (`execute_tool`), attribute NAMES from the OpenTelemetry GenAI
+//     semantic conventions where one exists (`gen_ai.operation.name`, `gen_ai.tool.name`, `gen_ai.tool.call.id`)
+//     and `ap.*` for what this substrate adds (capability, risk, the authority decision, the receipt digest).
+//     Vendor-neutral: an OTLP body is one function away (`otlpTracesOf`), and the SDK exporter with batching
+//     and gRPC is a sibling's (spec 351 §2.3) — this file is the mapping, which is the part that must be right.
+//
+//   · PROVENANCE — the durable half of the record, written into the acting agent's VAULT (ADR-0055: the DO
+//     copy is a rebuild, the vault is the record): per step, what ran, under which authority, with what
+//     verdict, leaving which receipt — and never the arguments, the results or the words.
+//
+// THE FIREWALL. A trace leaves the estate; a vault record outlives the run. Neither may carry what the run
+// was ABOUT: not the utterance, not a step's arguments, not a counterparty's address, not a result. What
+// they carry is what was DONE — names, ids, digests, verdicts, timings. The allowlist below is the whole of
+// it; `assertFirewalled` re-reads every value against the record and throws naming the leak, so a new
+// attribute cannot quietly widen the export. A payee is a digest away from a receipt, never in a span.
+import { engagementsOf, variantDigestOf } from './trace-facts.js';
+import { isArtifactRef, resultFactsOf } from './artifacts.js';
+/** The attribute names a span MAY carry — the firewall's allowlist. Anything else is refused at export. */
+export const SPAN_ATTRIBUTE_ALLOWLIST = new Set([
+    // OpenTelemetry GenAI semantic conventions (names only; values are ours)
+    'gen_ai.operation.name', 'gen_ai.agent.id', 'gen_ai.tool.name', 'gen_ai.tool.call.id', 'gen_ai.tool.type',
+    'gen_ai.conversation.id',
+    // this substrate
+    'ap.run.ref', 'ap.run.outcome', 'ap.intent.digest', 'ap.plan.steps', 'ap.plan.rationale.digest',
+    'ap.step.ref', 'ap.step.index', 'ap.step.status', 'ap.step.replayed', 'ap.step.skipped',
+    'ap.capability.id', 'ap.capability.action', 'ap.risk',
+    // Spec 390 W2 — the `ap.` taxonomy: the verdict and the mandate by reference; the archetype (playbook).
+    'ap.authority.verdict', 'ap.authority.mandate.ref', 'ap.authority.after_approval',
+    'ap.authority.chain.depth', 'ap.authority.chain.digest',
+    'ap.receipt.digest', 'ap.receipt.input.digest', 'ap.receipt.output.digest',
+    'ap.agent.archetype', 'ap.agent.archetype.version', 'ap.agent.archetype.commitment',
+    'ap.effects.count', 'ap.effects.failed', 'ap.decisions.count',
+    'ap.delegated_to.agent_digest', 'ap.error.class',
+    // Spec 381 W2 — trace context across agents: which run this one answers, as ids.
+    'ap.trace.origin', 'ap.link.kind',
+    // Spec 390 W1 — the span ↔ PROV bridge: the activity this span IS, the bundle it lives in, its plan step.
+    'ap.prov.activity.id', 'ap.prov.bundle.id', 'ap.prov.plan.id', 'ap.prov.plan.step.id',
+    // Spec 390 W3 — the authority stages, the model calls and the outcome as spans: GenAI names for the model
+    // calls (`gen_ai.provider.name`, `gen_ai.request.model` — never `gen_ai.system`), the route's reason
+    // (provider names and token counts), the standing relation, the anchors AS DIGESTS, the one public fact
+    // a step may cite (its chain transaction), and the approval's record count.
+    'gen_ai.provider.name', 'gen_ai.request.model',
+    'ap.plan.planner', 'ap.route.policy', 'ap.route.because',
+    'ap.standing.relation', 'ap.agent.anchor.digest', 'ap.agent.principal.digest',
+    'ap.action.tx_hash', 'ap.approval.records',
+    // Spec 390 W4 — span events and metrics: refusal / denial reason CODES, which model call a metric counts.
+    'ap.refusal.codes', 'ap.reason.codes', 'ap.model.call',
+]);
+/** Spec 390 — the PROV ids a span names, derived exactly as `provenance.harnessIds` derives them (the two
+ *  packages cannot import each other; `run-export.test.ts` asserts they agree). */
+export const PROV_ID_BASE = 'urn:ap:prov:';
+export const provIds = {
+    run: (runRef) => `${PROV_ID_BASE}act:${runRef}`,
+    step: (runRef, stepRef) => `${PROV_ID_BASE}act:${runRef}:${stepRef}`,
+    bundle: (runRef) => `${PROV_ID_BASE}bundle:${runRef}`,
+    plan: (runRef) => `${PROV_ID_BASE}plan:${runRef}`,
+    planStep: (runRef, stepRef) => `${PROV_ID_BASE}plan:${runRef}:step:${stepRef}`,
+};
+/** Web Crypto, so this file runs wherever the loop runs (a Worker, Node ≥ 20, a browser) with no import. */
+const sha256 = async (s) => {
+    const bytes = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(s)));
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+};
+const canonical = (v) => JSON.stringify(v, (_k, x) => (x && typeof x === 'object' && !Array.isArray(x)) ? Object.keys(x).sort().reduce((o, k) => { o[k] = x[k]; return o; }, {}) : x);
+/** The digest of a receipt as recorded — the one thing a span carries that names an act. */
+export async function receiptDigest(r) {
+    return `0x${await sha256(canonical(r))}`;
+}
+/** A receipt's `inputDigest`/`outputDigest` is a DIGEST only when it looks like one: this estate also records
+ *  `json:{…}` (the arguments verbatim, for a replay to match on), which is exactly what must not leave. A
+ *  non-hash is hashed here, so the export carries a commitment to the arguments and never the arguments. */
+const asDigest = async (v) => {
+    if (!v)
+        return undefined;
+    return /^0x[0-9a-fA-F]{64}$/.test(v) ? v.toLowerCase() : `0x${await sha256(v)}`;
+};
+/** W3C-sized ids derived from references: 16-byte trace, 8-byte span. Correlation, never trust (spec 390). */
+export const traceIdOf = async (runRef) => (await sha256(`trace:${runRef}`)).slice(0, 32);
+export const spanIdOf = async (runRef, stepRef) => (await sha256(`span:${runRef}:${stepRef ?? 'run'}`)).slice(0, 16);
+/** Spec 390 W2 — THE TRACE A RUN BELONGS TO, and what its root span is parented to. The wire wins: a
+ *  `traceparent` the request arrived with names the caller's trace and span. Absent that, a routed or
+ *  handed-off run derives the sender's trace from the run it answers (381 W2); a fresh run derives its own.
+ *  One rule, used by the spans and by the provenance view, so the graph and the trace name the same trace. */
+export async function traceIdFor(record) {
+    const answers = record.receipts.map((r) => r.binding?.correlation?.inResponseTo).find((x) => x?.runRef);
+    const origin = answers?.runRef ? { runRef: answers.runRef, ...(answers.stepRef ? { stepRef: answers.stepRef } : {}) } : undefined;
+    if (record.traceContext)
+        return { traceId: record.traceContext.traceId, parentSpanId: record.traceContext.parentSpanId, ...(origin ? { origin } : {}) };
+    if (origin)
+        return { traceId: await traceIdOf(origin.runRef), parentSpanId: await spanIdOf(origin.runRef, origin.stepRef ?? null), origin };
+    return { traceId: await traceIdOf(record.runRef) };
+}
+/** An address, wherever it appears in a value — what a span must never carry (it names a party). */
+/** A standalone 40-hex token — a 64-hex digest contains a 40-hex run and is not an address. */
+const ADDRESS = /(?<![0-9a-fA-Fx])0x[0-9a-fA-F]{40}(?![0-9a-fA-F])/;
+/** The step's terminal error, reduced to a CLASS (its first token) — the message may quote an argument. */
+const errorClass = (e) => {
+    if (!e)
+        return undefined;
+    const m = e.match(/^([a-z_][a-z0-9_]*)\s*[:—-]/i);
+    return m ? m[1] : 'error';
+};
+/** The run as spans. Pure; the same record always yields the same trace. */
+export async function spansOf(record) {
+    // Spec 381 W2 — ONE TRACE ACROSS AGENTS. A routed or handed-off run records which run and step it answers
+    // (`binding.correlation.inResponseTo`, spec 366/376). Ids are derived from run references, so the receiver
+    // JOINS the sender's trace without any header: its trace id is the sender's, and its root span's parent
+    // is the sender's step span. One hop is what a receiver knows; a receiver of a receiver joins its own
+    // sender, which is the same trace when every hop derives the same way. Nothing else is carried.
+    const { traceId, parentSpanId, origin: answers } = await traceIdFor(record);
+    const receiptsByStep = new Map(record.receipts.filter((r) => !r.stepRef.endsWith(':compensate')).map((r) => [r.stepRef, r]));
+    // The root begins no later than anything under it: the request's arrival when recorded, else the first
+    // stamped event, else the first receipt (a record from before stamps).
+    const firstStamp = Math.min(...record.events.map((e) => (typeof e.at === 'number' && e.at > 0 ? e.at : Number.POSITIVE_INFINITY)));
+    const startedMs = Math.min(record.receivedAt ?? Number.POSITIVE_INFINITY, firstStamp, record.receipts.length ? Math.min(...record.receipts.map((r) => r.startedAt * 1000)) : record.at);
+    const rootId = await spanIdOf(record.runRef, null);
+    const intentDigest = record.receipts.find((r) => r.binding?.intentDigest)?.binding?.intentDigest;
+    const root = {
+        traceId, spanId: rootId, name: 'invoke_agent', kind: 'SERVER',
+        ...(parentSpanId ? { parentSpanId } : {}),
+        startMs: Math.min(startedMs, record.at), endMs: record.at,
+        // Spec 390 W1 — the GenAI conformance rules reserve OK for application code: instrumentation leaves a
+        // success UNSET and sets ERROR only on failure. A suspended run is not an error.
+        status: record.outcome === 'completed' || record.outcome === 'suspended' ? 'UNSET' : 'ERROR',
+        attributes: {
+            'gen_ai.operation.name': 'invoke_agent',
+            'ap.run.ref': record.runRef,
+            'ap.prov.activity.id': provIds.run(record.runRef),
+            'ap.prov.bundle.id': provIds.bundle(record.runRef),
+            'ap.prov.plan.id': provIds.plan(record.runRef),
+            ...(answers?.runRef ? { 'ap.trace.origin': answers.runRef } : {}),
+            'ap.run.outcome': record.outcome,
+            'ap.plan.steps': record.plan.steps.length,
+            ...(intentDigest ? { 'ap.intent.digest': intentDigest } : {}),
+            ...(record.plan.rationale ? { 'ap.plan.rationale.digest': `0x${await sha256(record.plan.rationale)}` } : {}),
+        },
+    };
+    const steps = await Promise.all(record.steps.map(async (s, i) => {
+        const r = receiptsByStep.get(s.stepRef);
+        const start = r ? r.startedAt * 1000 : root.startMs;
+        const end = r ? r.completedAt * 1000 : start;
+        const attrs = {
+            'gen_ai.operation.name': 'execute_tool',
+            'gen_ai.tool.name': s.toolId,
+            'gen_ai.tool.call.id': `${record.runRef}:${s.stepRef}`,
+            'gen_ai.tool.type': r?.capability ? 'capability' : 'read',
+            'ap.step.ref': s.stepRef,
+            'ap.step.index': i,
+            'ap.prov.activity.id': provIds.step(record.runRef, s.stepRef),
+            'ap.prov.bundle.id': provIds.bundle(record.runRef),
+            'ap.prov.plan.step.id': provIds.planStep(record.runRef, s.stepRef),
+            'ap.step.status': r?.status ?? (s.skipped ? 'skipped' : s.ok ? 'completed' : 'failed'),
+            ...(s.replayed ? { 'ap.step.replayed': true } : {}),
+            ...(s.skipped ? { 'ap.step.skipped': true } : {}),
+            ...(r?.capability ? { 'ap.capability.id': r.capability.id, 'ap.capability.action': r.capability.action } : {}),
+            ...(r ? { 'ap.risk': r.risk } : {}),
+            ...(r?.authority ? { 'ap.authority.verdict': r.authority.decision.decision, 'ap.authority.after_approval': r.authority.afterApproval, ...(r.authority.presentedRef ? { 'ap.authority.mandate.ref': r.authority.presentedRef } : {}) } : {}),
+            ...(r?.authority?.decision.evidence?.chain ? { 'ap.authority.chain.depth': r.authority.decision.evidence.chain.depth, 'ap.authority.chain.digest': r.authority.decision.evidence.chain.chainDigest } : {}),
+            ...(r ? { 'ap.receipt.digest': await receiptDigest(r) } : {}),
+            ...(r?.inputDigest ? { 'ap.receipt.input.digest': (await asDigest(r.inputDigest)) } : {}),
+            ...(r?.outputDigest ? { 'ap.receipt.output.digest': (await asDigest(r.outputDigest)) } : {}),
+            ...(r?.skillRef ? { 'ap.agent.archetype': r.skillRef.skillId, 'ap.agent.archetype.version': r.skillRef.version, 'ap.agent.archetype.commitment': r.skillRef.commitment } : {}),
+            ...(r?.effects?.length ? { 'ap.effects.count': r.effects.length, 'ap.effects.failed': r.effects.filter((e) => !e.ok).length } : {}),
+            ...(r?.decisions?.length ? { 'ap.decisions.count': r.decisions.length } : {}),
+            ...(r?.binding?.correlation?.delegatedTo?.agent ? { 'ap.delegated_to.agent_digest': `0x${await sha256(String(r.binding.correlation.delegatedTo.agent).toLowerCase())}` } : {}),
+            ...(errorClass(s.error ?? r?.error) ? { 'ap.error.class': errorClass(s.error ?? r?.error) } : {}),
+        };
+        // Spec 381 W2 — a step handed to another agent LINKS to that run's root span: same trace (the child
+        // derives its trace id from this run), so a viewer follows the link from the hand-off to the work.
+        // A ROUTED step (366) names the receiver's run on its result (`via.runRef` — an id, never what it was
+        // about); it links the same way, so the trace reads on from the hop to the subject's own run.
+        const childRun = r?.binding?.correlation?.delegatedTo?.runRef;
+        const routedRun = resultFactsOf(s.result)?.via?.runRef;
+        const links = childRun ? [{ traceId, spanId: await spanIdOf(childRun, null), attributes: { 'ap.link.kind': 'delegated_to' } }]
+            : typeof routedRun === 'string' && routedRun ? [{ traceId, spanId: await spanIdOf(routedRun, null), attributes: { 'ap.link.kind': 'routed_to' } }] : undefined;
+        return {
+            traceId, spanId: await spanIdOf(record.runRef, s.stepRef), parentSpanId: rootId,
+            name: `execute_tool ${s.toolId}`, kind: 'INTERNAL', startMs: start, endMs: Math.max(end, start),
+            status: (s.ok || s.skipped ? 'UNSET' : 'ERROR'), attributes: attrs,
+            ...(links ? { links } : {}),
+        };
+    }));
+    const stages = await stageSpansOf(record, { traceId, rootId, stepIds: new Map(steps.map((sp) => [String(sp.attributes['ap.step.ref']), sp.spanId])) });
+    attachEvents(record, root, steps);
+    return [root, ...steps, ...stages];
+}
+/** Spec 390 W4 — the record's STAMPED events on the span they belong to: run-level on the root, step-level on
+ *  the step's span. Names are the event types; attributes are classes and counts, never messages. */
+function attachEvents(record, root, steps) {
+    const byStep = new Map(steps.map((sp) => [String(sp.attributes['ap.step.ref']), sp]));
+    for (const e of record.events) {
+        if (typeof e.at !== 'number' || e.at <= 0)
+            continue;
+        const attrs = {};
+        switch (e.type) {
+            case 'PlanCreated':
+                attrs['ap.plan.steps'] = e.steps;
+                break;
+            case 'PlanRefused':
+                attrs['ap.refusal.codes'] = [...new Set(e.violations.map((v) => v.code))].join(',');
+                break;
+            case 'MandateChecked':
+                attrs['ap.authority.verdict'] = e.decision;
+                attrs['ap.authority.after_approval'] = e.afterApproval;
+                break;
+            case 'MandateDenied':
+                attrs['ap.reason.codes'] = [...new Set(e.reasons.map((r) => r.code))].join(',');
+                break;
+            case 'ApprovalDischarged':
+                attrs['ap.approval.records'] = e.records.length;
+                break;
+            case 'ToolInvoked':
+                attrs['ap.step.status'] = e.ok ? 'completed' : 'failed';
+                break;
+            case 'ReceiptCreated':
+                attrs['ap.step.status'] = e.status;
+                break;
+            case 'EffectFailed': {
+                const c = errorClass(e.error);
+                if (c)
+                    attrs['ap.error.class'] = c;
+                break;
+            }
+            case 'RunFailed': {
+                const c = errorClass(e.error);
+                if (c)
+                    attrs['ap.error.class'] = c;
+                break;
+            }
+            default: break;
+        }
+        const target = 'stepRef' in e && typeof e.stepRef === 'string' ? (byStep.get(e.stepRef) ?? root) : root;
+        (target.events ??= []).push({ name: e.type, timeMs: e.at, ...(Object.keys(attrs).length ? { attributes: attrs } : {}) });
+    }
+}
+/**
+ * Spec 390 W3 — THE AUTHORITY STAGES, THE MODEL CALLS AND THE OUTCOME AS SPANS, projected from the record's
+ * stamped events (`RunEvent.at`) and its planner summary. Nothing is instrumented inline: the same record
+ * yields the same tree, and the firewall stays the whole surface.
+ *
+ *   invoke_agent
+ *    ├── receive_request      the request's arrival → RunStarted: admission and preparation (session, standing, playbook), un-itemised
+ *    ├── identify_principal   instant, at run start — the standing this hop ran under (383 W2), the anchors as digests
+ *    ├── plan [model]         RunStarted → the first PlanCreated; `chat` on the model that planned, with the route's reason
+ *    ├── execute_tool <tool>  the step (381), and UNDER it:
+ *    │    ├── verify_mandate      StepProposed → MandateChecked (and again after an approval)
+ *    │    ├── await_approval      ApprovalRequested → ApprovalDischarged, when both landed in this record
+ *    │    └── perform_action      instant at the step's end when it left a chain transaction or effects
+ *    └── issue_outcome        RunCompleted → the record's time; `chat` on the model that composed
+ *
+ * A stage whose two stamps are not both on the record is not emitted — a record written before events
+ * were stamped simply has no stage spans, never guessed ones. `resolve_delegation` (the chain walk) is not
+ * a separate span: the verifier walks the chain inside `verify_mandate`, whose attributes carry the chain
+ * (depth, digest) — one span, said honestly. `retrieval` waits for a tool to DECLARE itself one.
+ */
+export async function stageSpansOf(record, ctx) {
+    const out = [];
+    const at = (e) => (typeof e?.at === 'number' && e.at > 0 ? e.at : undefined);
+    const first = (type, stepRef) => record.events.find((e) => e.type === type && (stepRef === undefined || e.stepRef === stepRef));
+    const receiptsByStep = new Map(record.receipts.filter((r) => !r.stepRef.endsWith(':compensate')).map((r) => [r.stepRef, r]));
+    const started = at(first('RunStarted'));
+    // A record written before events were stamped has NO stage spans — not even the ones a receipt could
+    // time — so a reader never sees a partial tree and mistakes it for the whole.
+    if (started === undefined)
+        return out;
+    const instant = async (name, ms, parent, key, attrs) => ({ traceId: ctx.traceId, spanId: await spanIdOf(record.runRef, key), parentSpanId: parent, name, kind: 'INTERNAL', startMs: ms, endMs: ms, status: 'UNSET', attributes: attrs });
+    // receive_request — what happened before the loop: admission, standing, the playbook. One honest span.
+    if (typeof record.receivedAt === 'number' && record.receivedAt > 0 && record.receivedAt <= started) {
+        out.push({
+            traceId: ctx.traceId, spanId: await spanIdOf(record.runRef, 'stage:receive_request'), parentSpanId: ctx.rootId,
+            name: 'receive_request', kind: 'SERVER', startMs: record.receivedAt, endMs: started, status: 'UNSET',
+            attributes: { 'gen_ai.operation.name': 'receive_request', 'ap.prov.activity.id': provIds.run(record.runRef) },
+        });
+    }
+    // The runtime's own windows, itemised (record.marks): each under the stage it fell in — before the loop under
+    // `receive_request`, after it under `issue_outcome` — so a slow turn names the read that was slow.
+    const completedAt = at(first('RunCompleted')) ?? at(first('RunFailed'));
+    const markParent = (m) => {
+        if (m.endMs <= started && typeof record.receivedAt === 'number' && record.receivedAt > 0 && record.receivedAt <= started)
+            return 'stage:receive_request';
+        if (completedAt !== undefined && m.startMs >= completedAt)
+            return 'stage:issue_outcome';
+        return null;
+    };
+    for (const [i, m] of (record.marks ?? []).entries()) {
+        const parentKey = markParent(m);
+        if (!parentKey)
+            continue;
+        out.push({
+            traceId: ctx.traceId, spanId: await spanIdOf(record.runRef, `mark:${i}:${m.name}`), parentSpanId: await spanIdOf(record.runRef, parentKey),
+            name: m.name, kind: 'INTERNAL', startMs: m.startMs, endMs: m.endMs, status: 'UNSET',
+            attributes: { 'gen_ai.operation.name': parentKey === 'stage:receive_request' ? 'receive_request' : 'issue_outcome', 'ap.prov.activity.id': provIds.run(record.runRef) },
+        });
+    }
+    // identify_principal — the standing and the anchors, as the receipts recorded them (383).
+    const standing = record.receipts.map((r) => r.binding?.standing).find((x) => x);
+    const actor = record.receipts.map((r) => r.binding?.actor).find((x) => x);
+    const chain = record.receipts.map((r) => r.authority?.decision.evidence?.chain).find((x) => x);
+    if (started !== undefined && (standing || actor || chain)) {
+        out.push(await instant('identify_principal', started, ctx.rootId, 'stage:identify_principal', {
+            'gen_ai.operation.name': 'identify_principal',
+            'ap.prov.activity.id': provIds.run(record.runRef),
+            ...(standing ? { 'ap.standing.relation': standing.relation } : {}),
+            ...(actor?.actingAgent ? { 'ap.agent.anchor.digest': `0x${await sha256(String(actor.actingAgent).toLowerCase())}` } : {}),
+            ...(chain?.accountabilityRoot ? { 'ap.agent.principal.digest': `0x${await sha256(String(chain.accountabilityRoot).toLowerCase())}` } : {}),
+        }));
+    }
+    // plan — the planner's call, by the model that made it and the reason it was routed there (388).
+    const planned = at(first('PlanCreated'));
+    if (started !== undefined && planned !== undefined) {
+        // Spec 414 A1e — read from the run's model calls and its variant (the planner summary is retired).
+        const pc = record.modelCalls?.find((m) => m.role === 'plan');
+        const model = pc?.model;
+        const provider = pc?.provider;
+        out.push({
+            traceId: ctx.traceId, spanId: await spanIdOf(record.runRef, 'stage:plan'), parentSpanId: ctx.rootId,
+            name: model ? `plan ${model}` : 'plan', kind: model ? 'CLIENT' : 'INTERNAL', startMs: started, endMs: Math.max(planned, started), status: 'UNSET',
+            attributes: {
+                'gen_ai.operation.name': model ? 'chat' : 'plan',
+                'ap.prov.activity.id': provIds.run(record.runRef),
+                'ap.prov.plan.id': provIds.plan(record.runRef),
+                'ap.plan.steps': record.plan.steps.length,
+                ...(record.variant?.plannerKind ? { 'ap.plan.planner': record.variant.plannerKind } : {}),
+                ...(model ? { 'gen_ai.request.model': model } : {}),
+                ...(provider ? { 'gen_ai.provider.name': provider } : {}),
+                ...(record.variant?.routePolicy ? { 'ap.route.policy': record.variant.routePolicy } : {}),
+                ...(pc?.routeReason ? { 'ap.route.because': pc.routeReason } : {}),
+            },
+        });
+    }
+    // per step: verify_mandate (twice when an approval intervened), await_approval, perform_action — under the step's span.
+    for (const s of record.steps) {
+        const parent = ctx.stepIds.get(s.stepRef);
+        if (!parent)
+            continue;
+        const r = receiptsByStep.get(s.stepRef);
+        const proposed = at(first('StepProposed', s.stepRef));
+        const checks = record.events.filter((e) => e.type === 'MandateChecked' && e.stepRef === s.stepRef);
+        const requested = at(first('ApprovalRequested', s.stepRef));
+        const discharged = at(first('ApprovalDischarged', s.stepRef));
+        let from = proposed;
+        for (const [i, c] of checks.entries()) {
+            const to = at(c);
+            if (from === undefined || to === undefined) {
+                from = to;
+                continue;
+            }
+            out.push({
+                traceId: ctx.traceId, spanId: await spanIdOf(record.runRef, `${s.stepRef}:stage:verify_mandate:${i}`), parentSpanId: parent,
+                name: 'verify_mandate', kind: 'INTERNAL', startMs: from, endMs: Math.max(to, from), status: c.decision === 'deny' ? 'ERROR' : 'UNSET',
+                attributes: {
+                    'gen_ai.operation.name': 'verify_mandate',
+                    'ap.step.ref': s.stepRef,
+                    'ap.prov.activity.id': provIds.step(record.runRef, s.stepRef),
+                    'ap.authority.verdict': c.decision,
+                    'ap.authority.after_approval': c.afterApproval,
+                    ...(r?.authority?.presentedRef ? { 'ap.authority.mandate.ref': r.authority.presentedRef } : {}),
+                    ...(r?.authority?.decision.evidence?.chain ? { 'ap.authority.chain.depth': r.authority.decision.evidence.chain.depth, 'ap.authority.chain.digest': r.authority.decision.evidence.chain.chainDigest } : {}),
+                },
+            });
+            // the second verification (after an approval) starts when the approval was discharged
+            from = discharged ?? to;
+        }
+        if (requested !== undefined && discharged !== undefined) {
+            const dischargedEvent = first('ApprovalDischarged', s.stepRef);
+            out.push({
+                traceId: ctx.traceId, spanId: await spanIdOf(record.runRef, `${s.stepRef}:stage:await_approval`), parentSpanId: parent,
+                name: 'await_approval', kind: 'INTERNAL', startMs: requested, endMs: Math.max(discharged, requested), status: 'UNSET',
+                attributes: { 'gen_ai.operation.name': 'await_approval', 'ap.step.ref': s.stepRef, 'ap.prov.activity.id': provIds.step(record.runRef, s.stepRef), 'ap.approval.records': dischargedEvent?.records.length ?? 0 },
+            });
+        }
+        const tx = resultFactsOf(s.result)?.txHash;
+        const txHash = typeof tx === 'string' && /^0x[0-9a-fA-F]{64}$/.test(tx) ? tx.toLowerCase() : undefined;
+        if (r && (txHash || r.effects?.length)) {
+            out.push(await instant('perform_action', r.completedAt * 1000, parent, `${s.stepRef}:stage:perform_action`, {
+                'gen_ai.operation.name': 'perform_action',
+                'ap.step.ref': s.stepRef,
+                'ap.prov.activity.id': provIds.step(record.runRef, s.stepRef),
+                ...(txHash ? { 'ap.action.tx_hash': txHash } : {}),
+                ...(r.effects?.length ? { 'ap.effects.count': r.effects.length, 'ap.effects.failed': r.effects.filter((e) => !e.ok).length } : {}),
+            }));
+        }
+    }
+    // issue_outcome — the composer's call and the reply, from the loop's end to the record's time.
+    const completed = at(first('RunCompleted')) ?? at(first('RunFailed'));
+    if (completed !== undefined && record.at >= completed) {
+        const c = record.modelCalls?.find((m) => m.role === 'compose');
+        const model = c?.model;
+        out.push({
+            traceId: ctx.traceId, spanId: await spanIdOf(record.runRef, 'stage:issue_outcome'), parentSpanId: ctx.rootId,
+            name: 'issue_outcome', kind: c?.provider ? 'CLIENT' : 'INTERNAL', startMs: completed, endMs: record.at, status: 'UNSET',
+            attributes: {
+                'gen_ai.operation.name': c?.provider ? 'chat' : 'issue_outcome',
+                'ap.prov.activity.id': provIds.run(record.runRef),
+                'ap.run.outcome': record.outcome,
+                ...(c?.provider ? { 'gen_ai.provider.name': c.provider } : {}),
+                ...(c?.provider && model ? { 'gen_ai.request.model': model } : {}),
+                ...(c?.routeReason ? { 'ap.route.because': c.routeReason } : {}),
+            },
+        });
+    }
+    return out;
+}
+/**
+ * THE FIREWALL, re-read. Every attribute must be allowlisted, and no value may carry an address, the
+ * intent's words, or any step's argument values. Throws naming the span and attribute, so a leak is a
+ * build failure and a test failure, never a quiet export.
+ */
+export function assertFirewalled(spans, record) {
+    const words = record.intent.goal.trim().toLowerCase();
+    const argValues = new Set();
+    const walk = (v) => {
+        if (v == null)
+            return;
+        if (typeof v === 'string') {
+            if (v.length >= 3)
+                argValues.add(v.toLowerCase());
+            return;
+        }
+        if (typeof v === 'object') {
+            for (const x of Object.values(v))
+                walk(x);
+        }
+    };
+    for (const s of record.plan.steps)
+        walk(s.args);
+    for (const s of record.steps)
+        walk(s.args);
+    for (const sp of spans) {
+        for (const [k, v] of Object.entries(sp.attributes)) {
+            if (!SPAN_ATTRIBUTE_ALLOWLIST.has(k))
+                throw new Error(`span ${sp.name}: attribute "${k}" is not allowlisted for export`);
+            const sv = String(v);
+            if (ADDRESS.test(sv))
+                throw new Error(`span ${sp.name}: attribute "${k}" carries an address`);
+            const lv = sv.toLowerCase();
+            if (words.length >= 3 && lv.includes(words))
+                throw new Error(`span ${sp.name}: attribute "${k}" carries the intent's words`);
+            for (const a of argValues)
+                if (!ADDRESS.test(a) && lv === a)
+                    throw new Error(`span ${sp.name}: attribute "${k}" carries a step argument`);
+        }
+        if (ADDRESS.test(sp.name))
+            throw new Error(`span name "${sp.name}" carries an address`);
+        for (const ev of sp.events ?? []) {
+            for (const [k, v] of Object.entries(ev.attributes ?? {})) {
+                if (!SPAN_ATTRIBUTE_ALLOWLIST.has(k))
+                    throw new Error(`span ${sp.name} event ${ev.name}: attribute "${k}" is not allowlisted for export`);
+                const sv = String(v).toLowerCase();
+                if (ADDRESS.test(sv))
+                    throw new Error(`span ${sp.name} event ${ev.name}: attribute "${k}" carries an address`);
+                if (words.length >= 3 && sv.includes(words))
+                    throw new Error(`span ${sp.name} event ${ev.name}: attribute "${k}" carries the intent's words`);
+                for (const a of argValues)
+                    if (!ADDRESS.test(a) && sv === a)
+                        throw new Error(`span ${sp.name} event ${ev.name}: attribute "${k}" carries a step argument`);
+            }
+        }
+    }
+}
+/** Spec 390 W4 — the same firewall over a run's metric attributes: allowlisted names, no address, no words. */
+export function assertMetricsFirewalled(points, record) {
+    const words = record.intent.goal.trim().toLowerCase();
+    for (const p of points) {
+        for (const [k, v] of Object.entries(p.attributes)) {
+            if (!SPAN_ATTRIBUTE_ALLOWLIST.has(k))
+                throw new Error(`metric attribute "${k}" is not allowlisted for export`);
+            const sv = String(v).toLowerCase();
+            if (ADDRESS.test(sv))
+                throw new Error(`metric attribute "${k}" carries an address`);
+            if (words.length >= 3 && sv.includes(words))
+                throw new Error(`metric attribute "${k}" carries the intent's words`);
+        }
+    }
+}
+/** The OTLP/HTTP JSON body for these spans (`ExportTraceServiceRequest`), for a collector's `/v1/traces`.
+ *  Pure: the caller posts it. `resource` names the exporting service (its attributes go through the same
+ *  allowlist as a span's would not — they name the SERVICE, never the run, so `service.name` is the one). */
+export function otlpTracesOf(spans, resource) {
+    const attr = (k, v) => ({ key: k, value: typeof v === 'string' ? { stringValue: v } : typeof v === 'boolean' ? { boolValue: v } : Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v } });
+    const KIND = { INTERNAL: 1, SERVER: 2, CLIENT: 3 };
+    const STATUS = { UNSET: 0, OK: 1, ERROR: 2 };
+    return {
+        resourceSpans: [{
+                resource: { attributes: [attr('service.name', resource.serviceName), ...(resource.version ? [attr('service.version', resource.version)] : [])] },
+                scopeSpans: [{
+                        scope: { name: '@agenticprimitives/orchestration', version: '1' },
+                        spans: spans.map((s) => ({
+                            traceId: s.traceId, spanId: s.spanId, ...(s.parentSpanId ? { parentSpanId: s.parentSpanId } : {}),
+                            name: s.name, kind: KIND[s.kind],
+                            startTimeUnixNano: String(BigInt(Math.round(s.startMs)) * 1000000n),
+                            endTimeUnixNano: String(BigInt(Math.round(s.endMs)) * 1000000n),
+                            attributes: Object.entries(s.attributes).map(([k, v]) => attr(k, v)),
+                            ...(s.links?.length ? { links: s.links.map((l) => ({ traceId: l.traceId, spanId: l.spanId, attributes: Object.entries(l.attributes ?? {}).map(([k, v]) => attr(k, v)) })) } : {}),
+                            ...(s.events?.length ? { events: s.events.map((e) => ({ name: e.name, timeUnixNano: String(BigInt(Math.round(e.timeMs)) * 1000000n), attributes: Object.entries(e.attributes ?? {}).map(([k, v]) => attr(k, v)) })) } : {}),
+                            status: { code: STATUS[s.status] },
+                        })),
+                    }],
+            }],
+    };
+}
+export async function provenanceOf(record, agent) {
+    const receiptsByStep = new Map(record.receipts.filter((r) => !r.stepRef.endsWith(':compensate')).map((r) => [r.stepRef, r]));
+    const ctx = (record.intent.context ?? {});
+    const asker = typeof ctx.asker === 'string' && ADDRESS.test(ctx.asker) ? ctx.asker.toLowerCase() : undefined;
+    const intentDigest = record.receipts.find((r) => r.binding?.intentDigest)?.binding?.intentDigest;
+    const playbook = record.receipts.find((r) => r.skillRef)?.skillRef;
+    const answers = record.receipts.map((r) => r.binding?.correlation?.inResponseTo).find((x) => x?.runRef);
+    const iso = (sec) => (typeof sec === 'number' && sec > 0 ? new Date(sec * 1000).toISOString() : undefined);
+    const isoMs = (ms) => (typeof ms === 'number' && ms > 0 ? new Date(ms).toISOString() : undefined);
+    // Spec 414 A1 — the engagements, derived and stamped, split into the run's and each step's.
+    const engaged = engagementsOf(record);
+    const runEngagements = engaged.filter((e) => !e.stepRef).map(({ capability, effect, version, offered, chose, rejected, intent }) => ({ capability, effect, ...(version ? { version } : {}), ...(offered?.length ? { offered } : {}), ...(chose?.length ? { chose } : {}), ...(rejected?.length ? { rejected } : {}), ...(intent ? { intent } : {}) }));
+    const stepEngagements = (stepRef) => engaged.filter((e) => e.stepRef === stepRef).map(({ capability, effect, version }) => ({ capability, effect, ...(version ? { version } : {}) }));
+    const variant = record.variant ? { digest: await variantDigestOf(record.variant), ...(record.variant.plannerKind ? { plannerKind: record.variant.plannerKind } : {}), ...(record.variant.routePolicy ? { routePolicy: record.variant.routePolicy } : {}), ...(record.variant.build ? { build: record.variant.build } : {}), ...(record.variant.toggles ? { toggles: record.variant.toggles } : {}) } : undefined;
+    return {
+        type: 'ap.run-provenance.v1',
+        runRef: record.runRef,
+        traceId: (await traceIdFor(record)).traceId,
+        spanId: await spanIdOf(record.runRef, null),
+        endedAt: new Date(record.at).toISOString(),
+        agent: agent.toLowerCase(),
+        ...(asker ? { asker } : {}),
+        ...(intentDigest ? { intentDigest } : {}),
+        outcome: record.outcome,
+        ...(playbook ? { playbook: { skillId: playbook.skillId, version: playbook.version, commitment: playbook.commitment } } : {}),
+        ...(answers ? { inResponseTo: { agent: String(answers.agent).toLowerCase(), runRef: answers.runRef, ...(answers.stepRef ? { stepRef: answers.stepRef } : {}) } } : {}),
+        ...(record.door ? { door: record.door } : {}),
+        ...(record.modelCalls?.length ? { modelCalls: record.modelCalls.map((m) => ({ role: m.role, ...(m.model ? { model: m.model } : {}), ...(m.provider ? { provider: m.provider } : {}), ...(m.promptDigest ? { promptDigest: m.promptDigest } : {}), ...(m.tokensIn !== undefined ? { tokensIn: m.tokensIn } : {}), ...(m.tokensOut !== undefined ? { tokensOut: m.tokensOut } : {}), ...(m.routeReason ? { routeReason: m.routeReason } : {}), ...(isoMs(m.startMs) ? { startedAt: isoMs(m.startMs) } : {}), ...(isoMs(m.endMs) ? { endedAt: isoMs(m.endMs) } : {}) })) } : {}),
+        ...(variant ? { variant } : {}),
+        // A starting state is projected by its DIGEST (`state:<digest>`); one named without a digest is a note on the record, not an entity.
+        ...(record.startingState?.digest ? { startingState: { digest: record.startingState.digest } } : {}),
+        ...(runEngagements.length ? { engagements: runEngagements } : {}),
+        // A step that never ran but left a receipt — an act parked for its authority, or suspended for an input — is a step of
+        // the run all the same: its receipt is the evidence that the harness reached it and what it was waiting for.
+        steps: await Promise.all([...record.steps, ...record.receipts.filter((r) => !r.stepRef.endsWith(':compensate') && !record.steps.some((s) => s.stepRef === r.stepRef)).map((r) => ({ stepRef: r.stepRef, toolId: r.toolId, args: {}, ok: false, result: undefined, error: undefined, skipped: false }))].map(async (s) => {
+            const r = receiptsByStep.get(s.stepRef);
+            const tx = resultFactsOf(s.result)?.txHash;
+            return {
+                stepRef: s.stepRef, toolId: s.toolId,
+                spanId: await spanIdOf(record.runRef, s.stepRef),
+                ...(r?.capability ? { capability: { id: r.capability.id, action: r.capability.action } } : {}),
+                ...(r ? { risk: r.risk } : {}),
+                status: r?.status ?? (s.skipped ? 'skipped' : s.ok ? 'completed' : 'failed'),
+                ...(iso(r?.startedAt) ? { startedAt: iso(r?.startedAt) } : {}),
+                ...(iso(r?.completedAt) ? { endedAt: iso(r?.completedAt) } : {}),
+                ...(r?.authority ? { authority: { presentedRef: r.authority.presentedRef, decision: r.authority.decision.decision, afterApproval: r.authority.afterApproval, ...(r.authority.decision.evidence?.chain ? { chain: r.authority.decision.evidence.chain } : {}) } } : {}),
+                ...(r?.binding?.actor ? { actor: r.binding.actor } : {}),
+                ...(r ? { receiptDigest: await receiptDigest(r) } : {}),
+                ...(r?.inputDigest ? { inputDigest: (await asDigest(r.inputDigest)) } : {}),
+                ...(r?.outputDigest ? { outputDigest: (await asDigest(r.outputDigest)) } : {}),
+                ...(typeof tx === 'string' && /^0x[0-9a-fA-F]{64}$/.test(tx) ? { txHash: tx.toLowerCase() } : {}),
+                // A hand-off names its child run on the correlation (376); a ROUTED step names the receiver's run on its
+                // result (`via`, 366 M8) — an id and the agent, never what it was about. Either way the step's activity
+                // was informed by that run, and the graph says so (spec 389 W3).
+                ...(() => {
+                    const via = resultFactsOf(s.result)?.via;
+                    const agent = r?.binding?.correlation?.delegatedTo?.agent ?? (typeof via?.agent === 'string' ? via.agent : undefined);
+                    const run = r?.binding?.correlation?.delegatedTo?.runRef ?? (typeof via?.runRef === 'string' ? via.runRef : undefined);
+                    return { ...(agent ? { delegatedTo: String(agent).toLowerCase() } : {}), ...(run ? { delegatedToRun: run } : {}) };
+                })(),
+                ...(r?.effects?.length ? { effects: r.effects.map((e) => ({ produces: e.produces, ok: e.ok })) } : {}),
+                ...(r?.decisions?.length ? { decisions: r.decisions.map((d) => ({ point: d.point, ruleId: d.ruleId })) } : {}),
+                ...(errorClass(s.error ?? r?.error) ? { errorClass: errorClass(s.error ?? r?.error) } : {}),
+                ...(isArtifactRef(s.result) ? { artifact: { recordType: s.result.recordType, digest: s.result.digest, bytes: s.result.bytes } } : {}),
+                ...(r?.observation ? { observation: { outcome: r.observation.outcome, ...(r.observation.providerRef ? { providerRef: r.observation.providerRef } : {}), observedAt: r.observation.observedAt } } : {}),
+                ...(r?.skill ? { skill: { id: r.skill.id, version: r.skill.version, contractDigest: r.skill.contractDigest } } : {}),
+                ...(stepEngagements(s.stepRef).length ? { engagements: stepEngagements(s.stepRef) } : {}),
+                ...(() => {
+                    const facts = resultFactsOf(s.result);
+                    const inv = facts?.invoked;
+                    if (!inv || typeof inv.executor !== 'string' || typeof inv.intent !== 'string')
+                        return {};
+                    const receipt = facts?.receipt && typeof facts.receipt === 'object' && !Array.isArray(facts.receipt) ? facts.receipt : undefined;
+                    return { invoke: { executor: inv.executor, intent: inv.intent, ...(receipt ? { receipt } : {}) } };
+                })(),
+            };
+        })),
+    };
+}
+/** The vault record key a run's provenance lives under, in the acting agent's vault. */
+export const RUN_PROVENANCE_RECORD_PREFIX = 'run.provenance:';
+export const runProvenanceRecordKey = (runRef) => `${RUN_PROVENANCE_RECORD_PREFIX}${runRef}`;
+//# sourceMappingURL=spans.js.map