agentfootprint 9.114.2 → 9.115.0

package/dist/esm/adapters/observability/otel.js

@@ -63,10 +63,66 @@
  *   context.evaluated         ↦  N span events `agentfootprint.skill.routing`
  *                                — SYNTHESIZED name (one per routing entry),
  *                                not a registry-verbatim forward; apart from
- *                                it and `agentfootprint.tool.not_dispatched`
- *                                above, span events use the registry name
+ *                                it, `agentfootprint.tool.not_dispatched`
+ *                                above and `agentfootprint.integrity.check`
+ *                                below, span events use the registry name
  *                                verbatim
  *
+ * ## What an evaluation tool reads
+ *
+ *   meta.sessionId            ↦  `gen_ai.conversation.id` on the agent, chat
+ *                                and execute_tool spans of a session-bound run
+ *                                — the SHA-256 DIGEST of the session id by
+ *                                default (`conversationId: 'raw'` for the id
+ *                                itself, safe only behind a verifying door);
+ *                                never the runId in its place
+ *   eval.score                ↦  `gen_ai.evaluation.result` — the spec's
+ *                                evaluation event, carried as a SPAN event
+ *                                (the spec's reference emitter logs it; this
+ *                                adapter speaks the Tracer API only). On the
+ *                                span it evaluates while the turn is open; on
+ *                                a short `agentfootprint.evaluation` span
+ *                                under the turn once it closed — and PARENTED
+ *                                only when the score's own meta places it in
+ *                                that run's session. Otherwise (every
+ *                                `agent.emit` after the run) it rides an
+ *                                `agentfootprint.evaluation` span of its own,
+ *                                unparented, naming the ref. `explanation`
+ *                                only under `captureContent`; `evidence` never
+ *   tools.absent /            ↦  span event on the call's own span: a COUNT
+ *   tools.coverage_declared      per list (checked / not_checked /
+ *                                cannot_cover), the suggested tool's name only
+ *                                when this strategy has seen that tool run —
+ *                                never a sentence the tool author wrote
+ *   agent.evidence_checked    ↦  span event: verdict + unsupported COUNT; the
+ *                                values only under `captureContent`
+ *   findings.standing         ↦  span event per row (ids, enums, counts; an
+ *                                unknown id as a flag only), at most
+ *                                {@link MAX_STANDING_EVENTS_PER_TURN} per turn
+ *                                then one `agentfootprint.findings.standing_overflow`
+ *                                (SYNTHESIZED); a count per standing on the
+ *                                agent span when the turn closes
+ *   integrity.disposition     ↦  filed AFTER turn_end. By default exported
+ *                                only when a row is actionable (findings, or
+ *                                wiring rot): a short
+ *                                `agentfootprint.integrity.disposition` span
+ *                                under the turn, one
+ *                                `agentfootprint.integrity.check` span event
+ *                                (SYNTHESIZED) per actionable row.
+ *                                `checkAccounting: 'all'` for every row
+ *   (captureToolContent only) ↦  `gen_ai.tool.call.arguments` /
+ *                                `gen_ai.tool.call.result` on the tool span of
+ *                                a call that ran and returned — the proposal
+ *                                snapshot with every rule-changed key
+ *                                withheld, and what the model READ; objects
+ *                                only; omitted over `maxContentChars`; never a
+ *                                code runner's program
+ *
+ * The structure events above ride the `explainability` switch; the
+ * evaluation event does not (it is a `gen_ai.*` signal, like the attributes).
+ * A span started after its parent ended (the disposition, a late score) is
+ * valid OTel; most trace views draw it outside the parent's bar.
+ *
  * ## Decisions = SPAN EVENTS, not attributes (design decision)
  *
  * Explainability signals (route decisions, skill routing, validation
@@ -89,16 +145,57 @@
  *
  * ## PII discipline
  *
- * Mirrors the #9 validation contract: attribute values NEVER echo
+ * Mirrors the #9 validation contract: by default attribute values NEVER echo
  * runtime VALUES that can carry PII —
  *   - tool args  → top-level key NAMES only (`agentfootprint.tool.args.keys`)
+ *     (by default; see `captureToolContent`)
  *   - tool results → `typeof` only (`agentfootprint.tool.result.type`)
+ *     (by default; see `captureToolContent`)
  *   - validation issues → path / expected / got TYPES (bounded upstream)
  *   - decide() evidence → rule labels, operators, thresholds (developer
  *     constants) and the engine's redaction-aware value SUMMARIES
- *   - userPrompt / llm content / thinking → never emitted
+ *   - userPrompt / llm content / thinking → never emitted (by default; see
+ *     `captureContent`)
  *   - error.fatal → stage + scope only (error MESSAGES can echo values)
  *   - credential events carry no secrets by construction (registry contract)
+ *   - the session id → its SHA-256 digest (`conversationId`)
+ *   - absence / coverage events → list COUNTS, and the suggested tool's NAME
+ *     only when this strategy has seen that tool run; never
+ *     `looked_for`, a `what` / `why`, `tryInstead` or an unregistered
+ *     `tryInsteadTool.tool` — any field a tool author writes can interpolate
+ *     an argument (coverage README, "What that does not close"). The EVENT
+ *     never carries them, content on or off; under `captureToolContent` an
+ *     `absent()` call's result (the envelope itself) does, as its
+ *     `gen_ai.tool.call.result`, beside the arguments any interpolation came
+ *     from
+ *   - evidence verdict → the unsupported COUNT; findings → ids, enums,
+ *     counts, never the model's lines (an id the model wrote that names no
+ *     result is a flag, not the id); disposition → check names + counts
+ *   - eval.score → metric name, score, label (a vocabulary word by contract),
+ *     target words from the payload's closed vocabularies; `evidence` never
+ *   - EVERY string attribute outside the content switches is capped at 256
+ *     characters and every list at 20 items plus an overflow marker, in one
+ *     funnel (`capAttrs`) —
+ *     whoever chose the value, a caller-sized session id or a model-written
+ *     id cannot choose the size of an attribute. A capped value is cut with
+ *     `…` (never mid surrogate pair): a cut id is no longer the id. Span
+ *     NAMES carry a tool or model name at most 64 characters
+ *     (`spanNamePart`), since a tool name is the model's text when it names
+ *     no registered tool
+ *   - the session digest hashes the id's UTF-8 bytes, where every lone
+ *     surrogate becomes U+FFFD: two ids differing only in a lone surrogate
+ *     share a digest. Library-minted ids are UUIDs; documented, not handled
+ *
+ * Two content switches, each off by default: `captureContent` (the turn's
+ * prompt and answer, the evidence gate's unsupported values, an evaluation's
+ * explanation) and `captureToolContent` (tool arguments and results). The
+ * adapter redacts nothing of its own: it exports what the events carry. A
+ * call's arguments are the proposal `tool_start` carried, SERIALIZED THEN
+ * (the engine hands the same object to the tool, which may write into it),
+ * with every key `tool_end` names in `changedArgKeys` — a rule rewrote it,
+ * or the tool's own `redact` policy hides it — withheld as `'REDACTED'`; the
+ * result is what the model read (`modelResult`, after the `onToolResult`
+ * scrub). Never a raw value a rule replaced, never a value a rule added.
  *
  * @example Basic — Honeycomb via OTLP
  * ```ts
@@ -132,7 +229,9 @@
  * });
  * ```
  */
+import { filedNothing } from '../../integrity/disposition/ledger.js';
 import { lazyRequire } from '../../lib/lazyRequire.js';
+import { sha256Hex } from '../../lib/time-travel/sha256.js';
 import { rateLimitedConsoleSink } from './deliveryErrors.js';
 // ─── Bounding helpers (PII / cardinality discipline) ─────────────────
 /** Hard caps for attribute payloads. Evidence is bounded upstream
@@ -141,7 +240,27 @@ const MAX_ATTR_CHARS = 256;
 const MAX_LIST_ITEMS = 20;
 function bound(value) {
     const s = typeof value === 'string' ? value : JSON.stringify(value) ?? String(value);
-    return s.length > MAX_ATTR_CHARS ? `${s.slice(0, MAX_ATTR_CHARS - 1)}…` : s;
+    return s.length > MAX_ATTR_CHARS ? `${cutAt(s, MAX_ATTR_CHARS - 1)}…` : s;
+}
+/**
+ * The first `n` UTF-16 units of `s`, one fewer when the cut would split a
+ * surrogate pair — a lone high surrogate is not valid Unicode, and a strict
+ * OTLP/JSON decoder rejects it.
+ */
+function cutAt(s, n) {
+    const code = s.charCodeAt(n - 1);
+    return s.slice(0, code >= 0xd800 && code <= 0xdbff ? n - 1 : n);
+}
+/** The longest model- or caller-supplied text a span NAME carries. */
+const MAX_SPAN_NAME_PART = 64;
+/**
+ * A tool or model name as a span-name component. Span names never pass
+ * {@link capAttrs}, and a tool name is the MODEL's text when it names no
+ * registered tool — so it is capped here (registered names are at most 64
+ * characters by the providers' own rule, and pass unchanged).
+ */
+function spanNamePart(name) {
+    return name.length > MAX_SPAN_NAME_PART ? `${cutAt(name, MAX_SPAN_NAME_PART - 1)}…` : name;
 }
 function boundList(items) {
     const capped = items.slice(0, MAX_LIST_ITEMS).map(bound);
@@ -149,6 +268,49 @@ function boundList(items) {
         ? [...capped, `…+${items.length - MAX_LIST_ITEMS} more`]
         : capped;
 }
+/**
+ * The CONTENT attributes — the ones a content switch opened on purpose, each
+ * with its own size rule (tool content and the explanation: omitted over
+ * `maxContentChars`, never cut; `gen_ai.task.*`: exported as they always
+ * were). Every OTHER string leaving this adapter is capped by
+ * {@link capAttrs}.
+ */
+const CONTENT_KEYS = new Set([
+    'gen_ai.task.input',
+    'gen_ai.task.output',
+    'gen_ai.tool.call.arguments',
+    'gen_ai.tool.call.result',
+    'agentfootprint.tool.args.content',
+    'agentfootprint.tool.result.content',
+    'gen_ai.evaluation.explanation',
+]);
+/**
+ * The ONE cap on the way out: every string attribute — span, span event, the
+ * flattened fallback — at most {@link MAX_ATTR_CHARS}, every string list at
+ * most {@link MAX_LIST_ITEMS} items, except {@link CONTENT_KEYS}. The
+ * projections bound what they build; this funnel is what makes "every
+ * exported string is capped" true of fields nobody thought to bound — a
+ * caller-sized session id, a principal, a label. Returns the SAME object
+ * when nothing needed a cap, so an unaffected span is byte-identical.
+ */
+function capAttrs(attrs) {
+    let out;
+    for (const [key, value] of Object.entries(attrs)) {
+        if (CONTENT_KEYS.has(key))
+            continue;
+        let capped = value;
+        if (typeof value === 'string' && value.length > MAX_ATTR_CHARS)
+            capped = bound(value);
+        else if (Array.isArray(value) &&
+            (value.length > MAX_LIST_ITEMS || value.some((item) => item.length > MAX_ATTR_CHARS)))
+            capped = boundList(value);
+        if (capped !== value) {
+            out ??= { ...attrs };
+            out[key] = capped;
+        }
+    }
+    return out ?? attrs;
+}
 /** Render one rule's operator-level conditions as compact strings:
  *  `creditScore gt 700 → 750 (true)`. Value summaries come from the
  *  engine already bounded + redaction-aware — we only re-cap length. */
@@ -193,6 +355,218 @@ function looksLikeDecideEvidence(value) {
         value !== null &&
         Array.isArray(value.rules));
 }
+/** Name the closed standing vocabulary once — the per-turn counts key on it. */
+const STANDINGS = ['fact', 'open', 'noise', 'ruled-out'];
+/**
+ * Standing span events written per turn. The MODEL chooses how many standing
+ * rows it files, and a real OTel SDK keeps 128 events per span by evicting
+ * the OLDEST: unbounded rows would let a model (or a prompt injection in a
+ * tool result) push the span's earlier record — its route decision — off
+ * the wire. Past the cap, rows are counted and summarized once.
+ */
+const MAX_STANDING_EVENTS_PER_TURN = 32;
+/** The default ceiling on one exported CONTENT value, in characters. */
+const DEFAULT_MAX_CONTENT_CHARS = 65_536;
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Text that is a serialized plain object — the "serialized string" the spec
+ *  says to take as the object it encodes. Only text opening with `{` is
+ *  parsed; the caller has already refused anything over the ceiling. */
+function isSerializedObject(text) {
+    if (!text.trimStart().startsWith('{'))
+        return false;
+    try {
+        return isPlainObject(JSON.parse(text));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A tool call's arguments or result, as this adapter may export it:
+ *
+ *   - a plain object, or text that parses to one → the spec's
+ *     `gen_ai.tool.call.arguments` / `.result`, as a JSON string (the spec's
+ *     span form: its schema is `{"type": "object"}`, and OTel JS span
+ *     attributes hold no objects);
+ *   - anything else — plain text, a number, an array, the string `"123"` —
+ *     → `agentfootprint.tool.<args|result>.content`: text verbatim, other
+ *     values as JSON. Never the spec attribute, so a string is never
+ *     exported as the number it spells;
+ *   - over `maxChars` → neither: `agentfootprint.tool.<…>.omitted_chars`
+ *     states the size. Never a cut value, which reads as complete data;
+ *   - nothing serializable (undefined, a function, a cycle, a BigInt) → {}.
+ */
+function toolContentAttrs(kind, value, maxChars) {
+    const specKey = kind === 'args' ? 'gen_ai.tool.call.arguments' : 'gen_ai.tool.call.result';
+    if (value === undefined)
+        return {};
+    let text;
+    if (typeof value === 'string')
+        text = value;
+    else {
+        try {
+            text = JSON.stringify(value);
+        }
+        catch {
+            return {};
+        }
+    }
+    if (text === undefined)
+        return {};
+    if (text.length > maxChars)
+        return { [`agentfootprint.tool.${kind}.omitted_chars`]: text.length };
+    const object = typeof value === 'string' ? isSerializedObject(value) : isPlainObject(value);
+    return { [object ? specKey : `agentfootprint.tool.${kind}.content`]: text };
+}
+const countOf = (list) => (Array.isArray(list) ? list.length : 0);
+/**
+ * `tools.absent` / `tools.coverage_declared` — a COUNT per declared list, and
+ * the suggested tool's NAME only when `knownTool` recognizes it as a tool this
+ * strategy has seen RUN (a call that returned without error — it is held, by
+ * construction). Never a sentence: `looked_for`, `what`, `why`, `tryInstead` —
+ * and an unrecognized `tryInsteadTool.tool`, which is as much author text as
+ * the rest — can each interpolate an argument (coverage README, "What that
+ * does not close"); an unrecognized suggestion says only that it exists. A
+ * registered tool the agent has not run yet is not recognized: the event
+ * carries no roster (that would change every `absent()` event's bytes), so
+ * this may omit a real name — never export text that is not one.
+ */
+function coverageAttrs(p, knownTool) {
+    const suggested = typeof p.tryInsteadTool?.tool === 'string';
+    return {
+        ...(typeof p.toolName === 'string' && { 'gen_ai.tool.name': p.toolName }),
+        ...(typeof p.toolCallId === 'string' && { 'gen_ai.tool.call.id': p.toolCallId }),
+        ...(typeof p.iteration === 'number' && { 'agentfootprint.iteration.index': p.iteration }),
+        'agentfootprint.coverage.checked.count': countOf(p.checked),
+        'agentfootprint.coverage.not_checked.count': countOf(p.notChecked),
+        'agentfootprint.coverage.cannot_cover.count': countOf(p.cannotCover),
+        ...(suggested &&
+            (knownTool(String(p.tryInsteadTool?.tool))
+                ? { 'agentfootprint.coverage.try_instead.tool': bound(p.tryInsteadTool?.tool) }
+                : { 'agentfootprint.coverage.try_instead.unregistered': true })),
+    };
+}
+/** `agent.evidence_checked` — the verdict and a COUNT; the unsupported
+ *  values themselves only under `captureContent`. */
+function evidenceVerdictAttrs(p, content) {
+    const unsupported = Array.isArray(p.unsupported) ? p.unsupported : [];
+    return {
+        ...(typeof p.action === 'string' && { 'agentfootprint.evidence.action': p.action }),
+        ...(typeof p.posture === 'string' && { 'agentfootprint.evidence.posture': p.posture }),
+        ...(typeof p.candidates === 'number' && { 'agentfootprint.evidence.candidates': p.candidates }),
+        'agentfootprint.evidence.unsupported.count': unsupported.length,
+        ...(typeof p.afterRevision === 'boolean' && {
+            'agentfootprint.evidence.after_revision': p.afterRevision,
+        }),
+        ...(p.evidenceTruncated === true && { 'agentfootprint.evidence.truncated': true }),
+        ...(typeof p.iteration === 'number' && { 'agentfootprint.iteration.index': p.iteration }),
+        ...(content &&
+            unsupported.length > 0 && {
+            'agentfootprint.evidence.unsupported.values': boundList(unsupported.map((u) => String(u.value))),
+        }),
+    };
+}
+/**
+ * `findings.standing` — ids, the enum and counts. The assertions, `line` and
+ * every other word the model wrote stay in the committed ledger. An
+ * `unknownId` row exports the FLAG only: its `toolCallId` is a string the
+ * MODEL wrote that names no result the run returned — model text, and
+ * nothing any reader could join on.
+ */
+function standingAttrs(p) {
+    const knownId = p.unknownId !== true && typeof p.toolCallId === 'string';
+    return {
+        ...(typeof p.standing === 'string' && { 'agentfootprint.findings.standing': p.standing }),
+        ...(knownId && { 'gen_ai.tool.call.id': bound(p.toolCallId) }),
+        ...(typeof p.toolName === 'string' && { 'gen_ai.tool.name': p.toolName }),
+        ...(typeof p.declaredOn === 'string' && {
+            'agentfootprint.findings.declared_on': p.declaredOn,
+        }),
+        ...(typeof p.assertionCount === 'number' && {
+            'agentfootprint.findings.assertion_count': p.assertionCount,
+        }),
+        ...(Array.isArray(p.conflictKeys) && {
+            'agentfootprint.findings.conflict_count': p.conflictKeys.length,
+        }),
+        ...(p.unknownId === true && { 'agentfootprint.findings.unknown_id': true }),
+        ...(typeof p.agrees === 'boolean' && { 'agentfootprint.findings.agrees': p.agrees }),
+        ...(typeof p.iteration === 'number' && { 'agentfootprint.iteration.index': p.iteration }),
+    };
+}
+/** One count per standing in the closed vocabulary — zeros included, since
+ *  the adapter saw every standing row the traced turn filed. */
+function standingCountAttrs(counts) {
+    const attrs = {};
+    for (const s of STANDINGS)
+        attrs[`agentfootprint.findings.${s.replace('-', '_')}.count`] = counts.get(s) ?? 0;
+    return attrs;
+}
+/** `integrity.disposition` rows summed — the "did any check fire?" a reader
+ *  filters on. Synthetic (canary) counts stay out, as they do on each row. */
+function dispositionSpanAttrs(p) {
+    const rows = Array.isArray(p.rows) ? p.rows : [];
+    const sum = (key) => rows.reduce((n, row) => n + (typeof row[key] === 'number' ? row[key] : 0), 0);
+    return {
+        ...(typeof p.posture === 'string' && { 'agentfootprint.integrity.posture': p.posture }),
+        ...(typeof p.workExisted === 'boolean' && {
+            'agentfootprint.integrity.work_existed': p.workExisted,
+        }),
+        'agentfootprint.integrity.checked': sum('checked'),
+        'agentfootprint.integrity.findings': sum('findings'),
+        'agentfootprint.integrity.not_applicable': sum('notApplicable'),
+        'agentfootprint.integrity.unreachable': sum('unreachable'),
+    };
+}
+/** One registered (check, seam) row — the check's name and its outcomes. */
+function dispositionRowAttrs(row) {
+    const n = (v) => (typeof v === 'number' ? v : 0);
+    return {
+        'agentfootprint.integrity.check.name': bound(row.check),
+        'agentfootprint.integrity.check.seam': bound(row.seam),
+        'agentfootprint.integrity.check.checked': n(row.checked),
+        'agentfootprint.integrity.check.findings': n(row.findings),
+        'agentfootprint.integrity.check.not_applicable': n(row.notApplicable),
+        'agentfootprint.integrity.check.unreachable': n(row.unreachable),
+        'agentfootprint.integrity.check.synthetic': n(row.synthetic),
+    };
+}
+/**
+ * `eval.score` → the GenAI semconv `gen_ai.evaluation.result` attributes
+ * (github.com/open-telemetry/semantic-conventions-genai,
+ * docs/gen-ai/gen-ai-events.md). The spec has no field for the target or the
+ * evaluator kind, so those ride this adapter's own names — and only as words
+ * of the payload's own closed vocabularies (a TypeScript union is not a
+ * runtime check; a hand-fed sentence in `target` is not exported). The
+ * explanation is content (a judge's reason can quote what it graded):
+ * `captureContent` only, and omitted — its size stated — over `maxChars`.
+ * `evidence` is a free-form record and is never exported.
+ */
+function evaluationAttrs(p, content, maxChars) {
+    const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+    const explanation = content && typeof p.explanation === 'string' ? p.explanation : undefined;
+    return {
+        'gen_ai.evaluation.name': bound(p.metricId),
+        ...(finite(p.value) && { 'gen_ai.evaluation.score.value': p.value }),
+        ...(typeof p.label === 'string' && { 'gen_ai.evaluation.score.label': bound(p.label) }),
+        ...(explanation !== undefined &&
+            (explanation.length > maxChars
+                ? { 'agentfootprint.eval.explanation.omitted_chars': explanation.length }
+                : { 'gen_ai.evaluation.explanation': explanation })),
+        ...(EVAL_TARGETS.has(p.target) && {
+            'agentfootprint.eval.target': p.target,
+        }),
+        ...(typeof p.targetRef === 'string' && {
+            'agentfootprint.eval.target_ref': bound(p.targetRef),
+        }),
+        ...(finite(p.threshold) && { 'agentfootprint.eval.threshold': p.threshold }),
+        ...(EVALUATORS.has(p.evaluator) && {
+            'agentfootprint.eval.evaluator': p.evaluator,
+        }),
+    };
+}
+/** `EvalScorePayload`'s closed vocabularies, checked at run time. */
+const EVAL_TARGETS = new Set(['iteration', 'turn', 'run', 'toolCall']);
+const EVALUATORS = new Set(['llm', 'fn', 'heuristic']);
 // ─── Strategy factory ────────────────────────────────────────────────
 export function otelObservability(opts) {
     if (!opts.serviceName) {
@@ -204,6 +578,10 @@ export function otelObservability(opts) {
     const explainability = opts.explainability !== false;
     const scopeName = opts.scopeName ?? 'agentfootprint';
     const captureContent = opts.captureContent === true;
+    const captureToolContent = opts.captureToolContent === true;
+    const maxContentChars = opts.maxContentChars ?? DEFAULT_MAX_CONTENT_CHARS;
+    const rawConversationId = opts.conversationId === 'raw';
+    const allCheckRows = opts.checkAccounting === 'all';
     // Lazy-resolve tracer if not injected. Defer the API import until
     // first event so consumers who don't actually fire events (no agent
     // run yet) don't even hit the OTel API surface.
@@ -231,12 +609,101 @@ export function otelObservability(opts) {
         return tracer;
     }
     const activeTurns = new Map();
+    /**
+     * Tool names this strategy has seen RUN — a `tool_end` without `error` or
+     * `notExecuted` — so a held tool, by construction. What a `tryInsteadTool`
+     * suggestion is recognized against. Bounded; names only.
+     */
+    const ranTools = new Set();
+    /**
+     * Tool names that filed a `tools.code_run` — a code runner. Its arguments
+     * ARE the generated program, which "must not reach an exporter"
+     * (`events/payloads.ts` · `ToolsCodeRunPayload`): under
+     * `captureToolContent` its calls export no arguments. `code_run` fires after
+     * the tool ran and BEFORE its `tool_end`, so the first call is covered too;
+     * a call that failed exports no content at all.
+     */
+    const codeRunners = new Set();
+    const MAX_TOOL_NAMES = 1024;
+    function remember(set, name) {
+        if (set.size >= MAX_TOOL_NAMES && !set.has(name))
+            return;
+        set.add(name);
+    }
+    /**
+     * Turns that have CLOSED (turn_end / error.fatal), by run id — so a late
+     * event can still find its run. Two events arrive late by construction: the
+     * checker accounting (`integrity.disposition`, filed in the run door's
+     * `finally`, after turn_end) and an evaluation scored after the run. A real
+     * SDK drops span events on an ENDED span, so a late event gets its own
+     * short child span. An unsampled turn is remembered too (no span), so its
+     * late events are dropped with it rather than exported loose.
+     *
+     * Bounded — the last {@link MAX_CLOSED_TURNS} — and cleared by `stop()`.
+     * The window is per strategy, and one strategy usually serves the whole
+     * process: in a busy server a late event for a run 32 turns back finds it
+     * forgotten. A forgotten run's id is still remembered (a string, in
+     * {@link forgottenRuns}), so "forgotten" is told apart from "never traced"
+     * and reported, never dropped in silence. Each held root keeps its span
+     * object (and, under `captureContent`, the task text on it) on the heap
+     * until it leaves the window.
+     */
+    const MAX_CLOSED_TURNS = 32;
+    const MAX_FORGOTTEN_RUNS = 1024;
+    const closedTurns = new Map();
+    /** run id → whether it was sampled, for runs that left the window. */
+    const forgottenRuns = new Map();
+    function rememberClosed(runId, t) {
+        closedTurns.delete(runId);
+        closedTurns.set(runId, {
+            ...(t.root !== undefined && { root: t.root }),
+            ...(t.sessionDigest !== undefined && { sessionDigest: t.sessionDigest }),
+        });
+        while (closedTurns.size > MAX_CLOSED_TURNS) {
+            const [oldest] = closedTurns.entries();
+            if (oldest === undefined)
+                break;
+            closedTurns.delete(oldest[0]);
+            forgottenRuns.set(oldest[0], oldest[1].root !== undefined);
+        }
+        while (forgottenRuns.size > MAX_FORGOTTEN_RUNS) {
+            const [oldest] = forgottenRuns.keys();
+            if (oldest === undefined)
+                break;
+            forgottenRuns.delete(oldest);
+        }
+    }
+    /** `gen_ai.conversation.id` for a span of this turn — or nothing. */
+    function conversationAttr(t) {
+        return t.conversationId !== undefined ? { 'gen_ai.conversation.id': t.conversationId } : {};
+    }
+    /** `gen_ai.task.<input|output>`, or its size when over `maxContentChars`. */
+    function taskContent(kind, text) {
+        return text.length > maxContentChars
+            ? { [`agentfootprint.task.${kind}.omitted_chars`]: text.length }
+            : { [`gen_ai.task.${kind}`]: text };
+    }
+    /** A non-empty `meta.sessionId`, or undefined. */
+    function sessionOf(event) {
+        const sessionId = event.meta?.sessionId;
+        return typeof sessionId === 'string' && sessionId !== '' ? sessionId : undefined;
+    }
     let stopped = false;
     // The fallback when the consumer wires nothing. Rate-limited; a
     // consumer-supplied sink is not. Armed at CONSTRUCTION — before 8.11.0 it
     // was installed lazily inside `_onError` itself, which meant any caller
     // reading the hook rather than calling the method found `undefined`.
     const consoleSink = rateLimitedConsoleSink('otel');
+    /** A failure this adapter must not swallow — through the strategy's own
+     *  `_onError`, so a hook assigned after construction is the one called. */
+    function report(error, event) {
+        try {
+            strategy._onError?.(error, event);
+        }
+        catch {
+            /* a failing sink must never break the agent loop */
+        }
+    }
     /**
      * Resolve the run anchor for an event.
      *
@@ -251,21 +718,46 @@ export function otelObservability(opts) {
         const meta = event.meta;
         return meta?.runId ?? event.payload?.runId;
     }
-    function pushSpan(turnState, name, attrs) {
-        // OTel parent-context wiring: we capture the parent in a context
-        // and start the new span under it. (For BYO SDK setups, the
-        // `trace.setSpan` + `context.with` pattern is canonical. For
-        // the test-injected tracer path, we just pass the parent as
-        // implicit context.)
-        const parent = turnState.stack[turnState.stack.length - 1]?.span;
+    /**
+     * Start a span under `parent` (a root when `parent` is undefined) — the ONE
+     * place spans are started. OTel parent-context wiring: we capture the
+     * parent in a context and start the new span under it. (For BYO SDK
+     * setups, the `trace.setSpan` + `context.with` pattern is canonical. For
+     * the test-injected tracer path, we just pass the parent as implicit
+     * context.) The parent may already have ENDED: OTel links a child by span
+     * context, so a span started after its parent closed is still its child.
+     */
+    function startSpanUnder(parent, name, attrs, root = false) {
         let ctx;
         if (parent && otelApi?.trace?.setSpan && otelApi?.context?.active) {
             ctx = otelApi.trace.setSpan(otelApi.context.active(), parent);
         }
-        const span = ensureTracer().startSpan(name, attrs ? { attributes: attrs } : undefined, ctx);
+        const options = attrs || root
+            ? { ...(attrs && { attributes: capAttrs(attrs) }), ...(root && { root: true }) }
+            : undefined;
+        return ensureTracer().startSpan(name, options, ctx);
+    }
+    function pushSpan(turnState, name, attrs) {
+        const span = startSpanUnder(turnState.stack[turnState.stack.length - 1]?.span, name, attrs);
         turnState.stack.push({ name, span });
         return span;
     }
+    /** A short span under `parent` carrying `events`, ended at once — how an
+     *  event lands under a turn it can no longer be written onto. */
+    function recordOnChildSpan(parent, name, attrs, events) {
+        const span = startSpanUnder(parent, name, attrs);
+        for (const e of events)
+            recordSpanEvent(span, e.name, e.attrs);
+        endSpan(span);
+    }
+    /** The root of a traced turn, open or recently closed — `undefined` for an
+     *  unsampled turn or a run this adapter never traced (or has forgotten). */
+    function rootOf(runId) {
+        const live = activeTurns.get(runId);
+        if (live !== undefined)
+            return live.root;
+        return closedTurns.get(runId)?.root;
+    }
     function popSpan(turnState, match) {
         let idx = turnState.stack.length - 1;
         if (match !== undefined) {
@@ -294,6 +786,10 @@ export function otelObservability(opts) {
         span.end();
     }
     function setAttrs(span, attrs) {
+        writeAttrs(span, capAttrs(attrs));
+    }
+    /** The raw write, for attributes already through {@link capAttrs}. */
+    function writeAttrs(span, attrs) {
         for (const [key, value] of Object.entries(attrs)) {
             try {
                 span.setAttribute(key, value);
@@ -306,9 +802,12 @@ export function otelObservability(opts) {
     /** Emit a span event (preferred) or flattened-attribute fallback —
      *  see "Decisions = SPAN EVENTS" in the module docs. */
     function recordSpanEvent(span, name, attrs) {
+        // Capped BEFORE flattening: the fallback prefixes every key, and a content
+        // key must still be recognized as one.
+        const capped = capAttrs(attrs);
         if (typeof span.addEvent === 'function') {
             try {
-                span.addEvent(name, attrs);
+                span.addEvent(name, capped);
                 return;
             }
             catch {
@@ -316,9 +815,9 @@ export function otelObservability(opts) {
             }
         }
         const flattened = {};
-        for (const [key, value] of Object.entries(attrs))
+        for (const [key, value] of Object.entries(capped))
             flattened[`${name}.${key}`] = value;
-        setAttrs(span, flattened);
+        writeAttrs(span, flattened);
     }
     function topSpan(t) {
         return t?.stack[t.stack.length - 1]?.span;
@@ -463,10 +962,285 @@ export function otelObservability(opts) {
                 });
                 break;
             }
+            // A tool's declared absence / coverage — on the call's OWN span while it
+            // is open (parallel calls interleave, so the stack top may be another
+            // call's), else the active span. Counts per list, never a sentence.
+            case 'agentfootprint.tools.absent':
+            case 'agentfootprint.tools.coverage_declared': {
+                const callId = typeof p.toolCallId === 'string' ? p.toolCallId : undefined;
+                const span = (callId !== undefined ? t.toolSpans.get(callId) : undefined) ?? top;
+                recordSpanEvent(span, event.type, coverageAttrs(p, (name) => ranTools.has(name)));
+                break;
+            }
+            // The evidence gate's verdict on one would-be-final answer.
+            case 'agentfootprint.agent.evidence_checked': {
+                recordSpanEvent(top, event.type, evidenceVerdictAttrs(p, captureContent));
+                break;
+            }
+            // One model standing on one earlier result; counted for turn_end. The
+            // MODEL decides how many rows it files, and a real SDK keeps 128
+            // events per span by evicting the OLDEST — so past a per-turn cap the
+            // rows are counted, not written, and one summary event says how many
+            // at the turn's close. The per-standing counts stay complete.
+            case 'agentfootprint.findings.standing': {
+                const row = p;
+                if (t.standingEvents < MAX_STANDING_EVENTS_PER_TURN) {
+                    t.standingEvents += 1;
+                    recordSpanEvent(top, event.type, standingAttrs(row));
+                }
+                else
+                    t.standingOmitted += 1;
+                if (row.standing !== undefined && STANDINGS.includes(row.standing)) {
+                    t.standingCounts ??= new Map();
+                    t.standingCounts.set(row.standing, (t.standingCounts.get(row.standing) ?? 0) + 1);
+                }
+                break;
+            }
             default:
                 break;
         }
     }
+    /**
+     * The turn's findings summary on the agent span, at whichever close the
+     * turn gets (turn_end, error.fatal, or `stop()` for a paused one): a count
+     * per standing when any row was filed, and the one overflow event when the
+     * per-turn cap held rows back.
+     */
+    function flushStandings(t) {
+        if (t.root === undefined || !explainability)
+            return;
+        if (t.standingCounts !== undefined)
+            setAttrs(t.root, standingCountAttrs(t.standingCounts));
+        if (t.standingOmitted > 0) {
+            recordSpanEvent(t.root, 'agentfootprint.findings.standing_overflow', {
+                'agentfootprint.findings.standing_events_omitted': t.standingOmitted,
+                'agentfootprint.findings.standing_events_written': t.standingEvents,
+            });
+        }
+    }
+    /** The proposal as `tool_start` carried it, serialized THEN — a snapshot, so
+     *  nothing written into the object later can reach the export. */
+    function snapshotArgs(toolName, args) {
+        let text;
+        try {
+            text = JSON.stringify(args);
+        }
+        catch {
+            text = undefined;
+        }
+        if (text === undefined)
+            return { toolName, chars: 0 };
+        return text.length > maxContentChars
+            ? { toolName, chars: text.length }
+            : { toolName, text, chars: text.length };
+    }
+    /**
+     * `captureToolContent`, for a call that RAN and RETURNED (no `error`, no
+     * `notExecuted`): its arguments — the proposal snapshot, with every key a
+     * rule changed or the tool's redaction hides (`changedArgKeys`) shown as
+     * `'REDACTED'`: withheld, never replaced by a value the event does not
+     * carry — and what the model READ (`modelResult` when a rule changed it,
+     * else `result`). A code runner's arguments are its generated program and
+     * are withheld. A call that failed or never ran exports no content. Shape
+     * and size by {@link toolContentAttrs}.
+     */
+    function toolContent(t, p, errored) {
+        const proposal = p.toolCallId !== undefined ? t.proposedArgs.get(p.toolCallId) : undefined;
+        if (p.toolCallId !== undefined)
+            t.proposedArgs.delete(p.toolCallId);
+        if (errored || p.notExecuted === true)
+            return {};
+        const read = Object.prototype.hasOwnProperty.call(p, 'modelResult') ? p.modelResult : p.result;
+        return {
+            ...argsContent(proposal, p.changedArgKeys ?? []),
+            ...toolContentAttrs('result', read, maxContentChars),
+        };
+    }
+    function argsContent(proposal, changed) {
+        if (proposal === undefined)
+            return {};
+        if (codeRunners.has(proposal.toolName))
+            return { 'agentfootprint.tool.args.withheld': 'code-runner' };
+        if (proposal.text === undefined)
+            return proposal.chars > 0 ? { 'agentfootprint.tool.args.omitted_chars': proposal.chars } : {};
+        if (changed.length === 0)
+            return toolContentAttrs('args', proposal.text, maxContentChars);
+        let parsed;
+        try {
+            parsed = JSON.parse(proposal.text);
+        }
+        catch {
+            return {};
+        }
+        if (!isPlainObject(parsed))
+            return {};
+        const shown = { ...parsed };
+        for (const key of changed)
+            shown[key] = 'REDACTED';
+        return toolContentAttrs('args', shown, maxContentChars);
+    }
+    // ─── Late-capable events (they may arrive after the turn closed) ───
+    /**
+     * The checker accounting, filed ONCE per run from the run door's `finally`
+     * — after turn_end on a finished run, after error.fatal on a failed one,
+     * with the turn still open on a paused one. When it is exported it gets
+     * its own short span under the turn's root, so a reader finds it in one
+     * place whichever exit the run took.
+     *
+     * By default only when a row is ACTIONABLE — a check filed findings, or a
+     * registered check filed nothing while the run did work (the wiring rot
+     * `integrity/disposition/ledger.ts` · `filedNothing` names) — and only those
+     * rows ride as events. A healthy run exports nothing. `checkAccounting:
+     * 'all'` exports every row on every run.
+     */
+    function handleDisposition(event, runId) {
+        const root = rootOf(runId);
+        if (root === undefined)
+            return;
+        const p = event.payload;
+        const rows = Array.isArray(p.rows) ? p.rows : [];
+        const n = (v) => (typeof v === 'number' ? v : 0);
+        const actionable = (row) => n(row.findings) > 0 ||
+            (p.workExisted === true &&
+                filedNothing({
+                    checked: n(row.checked),
+                    notApplicable: n(row.notApplicable),
+                    unreachable: n(row.unreachable),
+                }));
+        const shown = allCheckRows ? rows : rows.filter(actionable);
+        if (!allCheckRows && shown.length === 0)
+            return;
+        recordOnChildSpan(root, 'agentfootprint.integrity.disposition', dispositionSpanAttrs(p), shown.map((row) => ({
+            name: 'agentfootprint.integrity.check',
+            attrs: dispositionRowAttrs(row),
+        })));
+    }
+    /** A score about a whole run can name it: `target` 'run' / 'turn' with the
+     *  run id as `targetRef` — the only join a score filed after the run has
+     *  (`agent.emit` stamps `runId: 'consumer-scope'`). A tool-call or
+     *  iteration ref names something else and never joins a run. */
+    function runNamedBy(p) {
+        return (p.target === 'run' || p.target === 'turn') && typeof p.targetRef === 'string'
+            ? p.targetRef
+            : undefined;
+    }
+    function heldRun(runId) {
+        const live = activeTurns.get(runId);
+        if (live !== undefined)
+            return {
+                runId,
+                live,
+                ...(live.root !== undefined && { root: live.root }),
+                ...(live.sessionDigest !== undefined && { sessionDigest: live.sessionDigest }),
+            };
+        const closed = closedTurns.get(runId);
+        return closed === undefined ? undefined : { runId, ...closed };
+    }
+    /**
+     * Where a verified score lands on a run whose turn is still OPEN: on the
+     * span it names while that span is open — the tool call (`targetRef` = its
+     * call id), the iteration (`targetRef` = its index) — else on a short span
+     * of its own under the turn's root, never on a sibling operation it does
+     * not name. A score about the run or the turn lands on the agent span.
+     */
+    function placeOnOpenTurn(t, root, p, attrs) {
+        const ref = typeof p.targetRef === 'string' ? p.targetRef : undefined;
+        let span;
+        if (p.target === 'toolCall')
+            span = ref !== undefined ? t.toolSpans.get(ref) : undefined;
+        else if (p.target === 'iteration')
+            span = t.stack.find((entry) => entry.name === `iteration:${ref ?? ''}`)?.span;
+        else
+            span = root;
+        if (span !== undefined)
+            recordSpanEvent(span, 'gen_ai.evaluation.result', attrs);
+        else
+            recordOnChildSpan(root, 'agentfootprint.evaluation', undefined, [
+                { name: 'gen_ai.evaluation.result', attrs },
+            ]);
+    }
+    /** A score this adapter may not (or cannot) place under a run: its own
+     *  root span, the ref it named as an attribute, and why it stands alone. */
+    function recordUnparented(attrs, reason) {
+        // `root`: a NEW trace, never a child of whatever span is active in the
+        // caller's context (an unrelated request being served) — unparented means
+        // unparented.
+        const span = startSpanUnder(undefined, 'agentfootprint.evaluation', { 'service.name': opts.serviceName, 'agentfootprint.eval.unparented': reason }, true);
+        recordSpanEvent(span, 'gen_ai.evaluation.result', attrs);
+        endSpan(span);
+    }
+    /**
+     * `eval.score` → `gen_ai.evaluation.result` (the spec's evaluation event,
+     * carried here as a SPAN event: this adapter speaks only the Tracer API).
+     *
+     * WHICH run: the one the score NAMES (`target` 'run' / 'turn', `targetRef`
+     * = a run id) when this adapter holds it; else the run the score was
+     * emitted from. A ref that names no run held here ('this-run', a label)
+     * falls back to the emitting run.
+     *
+     * WHETHER it may be parented there: only when the library can place the
+     * score in that run's session — it was emitted from inside that very run,
+     * or its own `meta.sessionId` is that run's session. Run ids are minted in
+     * sequence and anyone can write one, so a score that cannot show it
+     * belongs (every `agent.emit` after the run: no session on its meta) is
+     * exported on a span of its OWN, unparented, naming the ref — never under
+     * someone else's trace. Placement while the turn is open follows
+     * {@link placeOnOpenTurn}; after it closed, a short `agentfootprint.evaluation`
+     * span under the root (a finished span takes no events).
+     *
+     * Never silently lost: a run sampling dropped takes its scores with it; a
+     * run that left the closed-turn window is exported unparented AND reported
+     * through `onError`; a score with no `metricId` (the spec's one Required
+     * attribute) is reported. This path is best effort — the durable home for
+     * scores filed after the run is a score record, not a trace span.
+     */
+    function handleEvalScore(event, runId) {
+        const p = event.payload;
+        if (typeof p.metricId !== 'string' || p.metricId === '') {
+            report(new Error('otelObservability: an agentfootprint.eval.score without a metricId was not exported — ' +
+                'gen_ai.evaluation.name is the one attribute the spec requires.'), event);
+            return;
+        }
+        const attrs = evaluationAttrs(p, captureContent, maxContentChars);
+        const named = runNamedBy(p);
+        const namedRun = named !== undefined ? heldRun(named) : undefined;
+        // A ref naming a run this strategy FORGOT is still that run's score: it
+        // never falls back to the run it was emitted from.
+        const forgottenRef = namedRun === undefined && named !== undefined && forgottenRuns.has(named) ? named : undefined;
+        const target = forgottenRef !== undefined ? undefined : namedRun ?? heldRun(runId);
+        if (target === undefined) {
+            const ref = forgottenRef ?? named ?? runId;
+            const sampled = forgottenRuns.get(ref);
+            if (sampled === false)
+                return; // sampling dropped it; its scores go with it
+            if (sampled === true) {
+                recordUnparented(attrs, 'run-forgotten');
+                report(new Error(`otelObservability: an evaluation score names run '${bound(ref)}', which closed more ` +
+                    `than ${String(MAX_CLOSED_TURNS)} turns ago on this strategy — exported on its own ` +
+                    `span, unparented.`), event);
+                return;
+            }
+            recordUnparented(attrs, 'run-not-held');
+            return;
+        }
+        if (target.root === undefined)
+            return; // sampling dropped it
+        const scoreSession = sessionOf(event);
+        const verified = target.runId === runId ||
+            (scoreSession !== undefined &&
+                target.sessionDigest !== undefined &&
+                sha256Hex(scoreSession) === target.sessionDigest);
+        if (!verified) {
+            recordUnparented(attrs, 'owner-unverified');
+            return;
+        }
+        if (target.live !== undefined)
+            placeOnOpenTurn(target.live, target.root, p, attrs);
+        else
+            recordOnChildSpan(target.root, 'agentfootprint.evaluation', undefined, [
+                { name: 'gen_ai.evaluation.result', attrs },
+            ]);
+    }
     // ─── Event-to-span dispatch ────────────────────────────────────────
     function handleEvent(event) {
         if (stopped)
@@ -477,8 +1251,39 @@ export function otelObservability(opts) {
         switch (event.type) {
             case 'agentfootprint.agent.turn_start': {
                 const sampled = sampleRate >= 1 || Math.random() < sampleRate;
-                const turnState = { stack: [], sampled, toolSpans: new Map() };
+                // The CONVERSATION this run belongs to: `meta.sessionId` (9.4.0),
+                // stamped by `run(input, { sessionId })` and by `standingAgent` from
+                // the request's own session — the one a `SessionLifecycle` store
+                // (9.26.0) persists. It is the spec's `gen_ai.conversation.id` exactly:
+                // "the unique identifier for a conversation (session, thread)", and
+                // the spec rules out a stand-in ("a new UUID, a trace identifier …
+                // SHOULD NOT be used"), so a run that is not session-bound gets none —
+                // never the runId, which names ONE turn and would merge nothing and
+                // split everything in a backend's session view.
+                //
+                // WRITTEN AS A DIGEST by default (`conversationId`): at a door with no
+                // verifier the session id is the handle to the conversation, and a
+                // trace backend is read by many more people than the browser that
+                // minted it. The digest groups exactly as the id would; the raw id is
+                // an opt-in for doors that verify who may open a conversation.
+                const sessionId = sessionOf(event);
+                const sessionDigest = sessionId !== undefined ? sha256Hex(sessionId) : undefined;
+                const turnState = {
+                    stack: [],
+                    sampled,
+                    toolSpans: new Map(),
+                    toolNames: new Map(),
+                    standingEvents: 0,
+                    standingOmitted: 0,
+                    proposedArgs: new Map(),
+                    ...(sessionId !== undefined && {
+                        conversationId: rawConversationId ? sessionId : sessionDigest,
+                        sessionDigest,
+                    }),
+                };
                 activeTurns.set(runId, turnState);
+                closedTurns.delete(runId);
+                forgottenRuns.delete(runId);
                 if (sampled) {
                     const turnIndex = event.payload.turnIndex;
                     // `invoke_agent` span per the GenAI agent-span conventions.
@@ -486,10 +1291,8 @@ export function otelObservability(opts) {
                     // required) are back-filled on the first llm_start — unknown here.
                     // `userPrompt` rides the span ONLY when the consumer asked for it
                     // (`captureContent`) — see that option for what enabling it exports.
-                    // We emit `agentfootprint.run.id` (not `gen_ai.conversation.id`):
-                    // a run is one turn, not a conversation/session — agentfootprint
-                    // has no session primitive yet, and mislabeling would corrupt
-                    // backends' session grouping.
+                    // `agentfootprint.run.id` names the run (one turn) beside the
+                    // conversation id above — one session, many runs.
                     // WHO the run is for (9.11.0). This adapter maps selected signals
                     // onto spans rather than serializing the envelope — unlike the
                     // file / CloudWatch / AgentCore sinks, which write
@@ -503,6 +1306,7 @@ export function otelObservability(opts) {
                         'service.name': opts.serviceName,
                         'gen_ai.operation.name': 'invoke_agent',
                         'gen_ai.agent.name': opts.serviceName,
+                        ...conversationAttr(turnState),
                         'agentfootprint.run.id': runId,
                         ...(typeof turnIndex === 'number' && { 'agentfootprint.turn.index': turnIndex }),
                         // Absent when nobody named one — an anonymous run gets no
@@ -513,7 +1317,7 @@ export function otelObservability(opts) {
                         ...(actor?.tenant !== undefined && { 'agentfootprint.tenant.id': actor.tenant }),
                         ...(captureContent &&
                             typeof event.payload.userPrompt === 'string' && {
-                            'gen_ai.task.input': event.payload.userPrompt,
+                            ...taskContent('input', event.payload.userPrompt),
                         }),
                     });
                 }
@@ -529,7 +1333,8 @@ export function otelObservability(opts) {
                     const p = event.payload;
                     setAttrs(t.root, {
                         ...(captureContent &&
-                            typeof p.finalContent === 'string' && { 'gen_ai.task.output': p.finalContent }),
+                            typeof p.finalContent === 'string' &&
+                            taskContent('output', p.finalContent)),
                         ...(typeof p.totalInputTokens === 'number' && {
                             'gen_ai.usage.input_tokens': p.totalInputTokens,
                         }),
@@ -541,6 +1346,9 @@ export function otelObservability(opts) {
                         }),
                     });
                 }
+                // A count per findings standing (only when the turn filed any) and the
+                // overflow summary (only when the per-turn cap held rows back).
+                flushStandings(t);
                 // Defensive: end everything still on the stack.
                 while (t.stack.length > 0) {
                     const span = popSpan(t);
@@ -548,6 +1356,7 @@ export function otelObservability(opts) {
                         endSpan(span);
                 }
                 activeTurns.delete(runId);
+                rememberClosed(runId, t);
                 break;
             }
             case 'agentfootprint.agent.iteration_start': {
@@ -584,13 +1393,15 @@ export function otelObservability(opts) {
                 // unchanged — 'anthropic' / 'openai' / 'cohere' are already
                 // well-known semconv values; others ride as custom values (the
                 // spec permits them).
-                pushSpan(t, genAiNames && p.model ? `chat ${p.model}` : 'llm', {
+                pushSpan(t, genAiNames && p.model ? `chat ${spanNamePart(p.model)}` : 'llm', {
                     'gen_ai.operation.name': 'chat',
                     ...(p.model !== undefined && { 'gen_ai.request.model': p.model }),
                     ...(p.provider !== undefined && { 'gen_ai.provider.name': p.provider }),
                     ...(typeof p.temperature === 'number' && {
                         'gen_ai.request.temperature': p.temperature,
                     }),
+                    // Conditionally Required on inference spans "if available" (spec).
+                    ...conversationAttr(t),
                 });
                 // Back-fill the conditionally-required agent-span attrs now that
                 // the first inference call reveals provider + model.
@@ -666,20 +1477,30 @@ export function otelObservability(opts) {
                     break;
                 }
                 // Tool-execution span per GenAI semconv (`execute_tool`).
-                // Args: top-level key NAMES only — `gen_ai.tool.call.arguments`
-                // exists in the spec but is opt-in and carries raw values; we
-                // deliberately never emit it (PII / prompt-injection echo).
+                // Args: top-level key NAMES by default. The values ride
+                // `gen_ai.tool.call.arguments` — Opt-In in the spec, because they are
+                // raw (PII / prompt-injection echo) — ONLY under `captureToolContent`,
+                // SNAPSHOTTED here (serialized now — the tool receives this same
+                // object and may write into it) and exported at `tool_end`, once the
+                // rules have named the keys they changed (`changedArgKeys`).
                 const argKeys = p.args !== undefined && typeof p.args === 'object' ? Object.keys(p.args) : [];
-                const span = pushSpan(t, genAiNames ? `execute_tool ${toolName}` : `tool:${toolName}`, {
+                const nameInSpan = spanNamePart(toolName);
+                const span = pushSpan(t, genAiNames ? `execute_tool ${nameInSpan}` : `tool:${nameInSpan}`, {
                     'tool.name': toolName,
                     'gen_ai.operation.name': 'execute_tool',
                     'gen_ai.tool.name': toolName,
                     ...(p.toolCallId !== undefined && { 'gen_ai.tool.call.id': p.toolCallId }),
                     ...(p.protocol !== undefined && { 'agentfootprint.tool.protocol': p.protocol }),
                     ...(argKeys.length > 0 && { 'agentfootprint.tool.args.keys': boundList(argKeys) }),
+                    // Conditionally Required on execute_tool spans "if available" (spec).
+                    ...conversationAttr(t),
                 });
-                if (p.toolCallId !== undefined)
+                if (p.toolCallId !== undefined) {
                     t.toolSpans.set(p.toolCallId, span);
+                    t.toolNames.set(p.toolCallId, toolName);
+                    if (captureToolContent)
+                        t.proposedArgs.set(p.toolCallId, snapshotArgs(toolName, p.args));
+                }
                 break;
             }
             case 'agentfootprint.stream.tool_end': {
@@ -693,6 +1514,13 @@ export function otelObservability(opts) {
                 if (p.notDispatched !== undefined)
                     break;
                 const errored = p.error !== undefined && p.error !== false;
+                const ranName = p.toolCallId !== undefined ? t.toolNames.get(p.toolCallId) : undefined;
+                if (p.toolCallId !== undefined)
+                    t.toolNames.delete(p.toolCallId);
+                // A call that returned without error and was not refused ran a tool
+                // this agent holds — what a `tryInsteadTool` name is recognized by.
+                if (ranName !== undefined && !errored && p.notExecuted !== true)
+                    remember(ranTools, ranName);
                 // Correlate by toolCallId (the only identity ToolEndPayload
                 // carries) — parallel tool calls end out of LIFO order, so name
                 // matching alone would close the wrong span. Fallback chain
@@ -708,16 +1536,20 @@ export function otelObservability(opts) {
                 }
                 else {
                     span = popSpan(t, p.toolName !== undefined
-                        ? (name) => name === `tool:${p.toolName}` || name === `execute_tool ${p.toolName}`
+                        ? (name) => name === `tool:${spanNamePart(p.toolName ?? '')}` ||
+                            name === `execute_tool ${spanNamePart(p.toolName ?? '')}`
                         : (name) => name.startsWith('tool:') || name.startsWith('execute_tool '));
                 }
                 if (!span)
                     break;
-                // Result: TYPE only — never the value (PII discipline; mirrors
-                // the #9 contract and `gen_ai.tool.call.result` stays unemitted).
+                // Result: TYPE by default — never the value (PII discipline; mirrors
+                // the #9 contract). Content only under `captureToolContent`
+                // (`toolContent`): the proposal with rule-changed keys withheld, and
+                // what the model read.
                 setAttrs(span, {
                     'agentfootprint.tool.result.type': p.result === null ? 'null' : typeof p.result,
                     ...(errored && { 'error.type': '_OTHER' }), // boolean error flag — no class info
+                    ...(captureToolContent && toolContent(t, p, errored)),
                 });
                 endSpan(span, { error: errored });
                 break;
@@ -736,6 +1568,7 @@ export function otelObservability(opts) {
                         ...(p.scope !== undefined && { 'agentfootprint.error.scope': bound(p.scope) }),
                     });
                 }
+                flushStandings(t);
                 while (t.stack.length > 1) {
                     const span = popSpan(t);
                     if (span)
@@ -745,6 +1578,26 @@ export function otelObservability(opts) {
                 if (root)
                     endSpan(root, { error: true });
                 activeTurns.delete(runId);
+                // The run door's `finally` still files its checker accounting.
+                rememberClosed(runId, t);
+                break;
+            }
+            // A code runner ran: its NAME marks its calls' arguments (the program)
+            // as never exported. Names only; the event carries no code.
+            case 'agentfootprint.tools.code_run': {
+                const tool = event.payload.tool;
+                if (typeof tool === 'string')
+                    remember(codeRunners, tool);
+                break;
+            }
+            // Late-capable events: they may name a turn that has already closed.
+            case 'agentfootprint.eval.score': {
+                handleEvalScore(event, runId);
+                break;
+            }
+            case 'agentfootprint.integrity.disposition': {
+                if (explainability)
+                    handleDisposition(event, runId);
                 break;
             }
             // Other events — annotate / record on the topmost active span.
@@ -772,7 +1625,7 @@ export function otelObservability(opts) {
             }
         }
     }
-    return {
+    const strategy = {
         name: 'otel',
         capabilities: { events: true, traces: true },
         exportEvent: handleEvent,
@@ -786,6 +1639,7 @@ export function otelObservability(opts) {
             stopped = true;
             // Defensive: end any spans the agent loop didn't close.
             for (const [, t] of activeTurns) {
+                flushStandings(t);
                 while (t.stack.length > 0) {
                     const span = popSpan(t);
                     if (span)
@@ -794,6 +1648,8 @@ export function otelObservability(opts) {
                 t.toolSpans.clear();
             }
             activeTurns.clear();
+            closedTurns.clear();
+            forgottenRuns.clear();
         },
         /**
          * Where errors go. Overriding it works — assign `_onError`, or pass
@@ -851,5 +1707,6 @@ export function otelObservability(opts) {
             };
         },
     };
+    return strategy;
 }
 //# sourceMappingURL=otel.js.map