@deepstrike/sdk 0.2.61 → 0.2.63

package/dist/runtime/canonical-kernel-step.js

@@ -41,239 +41,186 @@ export function canonicalUnsupportedEffectResolution(effectId, effectKind) {
     };
 }
 /** The only ABI-v3 planned-step → Node host-action projection. */
-export function canonicalActionFromPlannedStep(plannedStep) {
-    if (plannedStep.disposition.kind === "terminal") {
-        const terminal = plannedStep.disposition.terminal;
-        const usage = asObject(terminal.usage);
-        let termination = String(terminal.kind ?? "failed");
-        let turnsUsed = Number(usage.turns ?? 0);
-        if (terminal.kind === "agent") {
-            const result = asObject(terminal.result);
-            termination = String(result.termination ?? "completed");
-            turnsUsed = Number(result.turns_used ?? turnsUsed);
-            const finalMessage = asObject(result.final_message);
-            const pace = asObject(result.pace_decision);
-            if (Object.keys(finalMessage).length > 0) {
-                return {
-                    kind: "done",
-                    effectId: "",
-                    result: {
-                        termination,
-                        turnsUsed,
-                        totalTokensUsed: totalUsageTokens(terminal),
-                        finalMessage: {
-                            role: String(finalMessage.role ?? "assistant"),
-                            content: String(finalMessage.content ?? ""),
-                            toolCalls: (Array.isArray(finalMessage.tool_calls) ? finalMessage.tool_calls : [])
-                                .map(value => {
-                                const call = asObject(value);
-                                return {
-                                    id: String(call.call_id ?? ""),
-                                    name: String(call.name ?? ""),
-                                    arguments: JSON.stringify(call.arguments ?? {}),
-                                };
-                            }),
-                        },
-                        ...(Object.keys(pace).length > 0
-                            ? {
-                                paceDecision: {
-                                    action: String(pace.action ?? "stop"),
-                                    ...(pace.delay_ms !== undefined ? { delayMs: Number(pace.delay_ms) } : {}),
-                                    reason: String(pace.reason ?? ""),
-                                    ...(pace.coerced_from ? { coercedFrom: String(pace.coerced_from) } : {}),
-                                },
-                            }
-                            : {}),
-                    },
-                };
-            }
-        }
-        else if (terminal.kind === "workflow") {
-            const outcome = asObject(terminal.outcome);
-            termination = String(outcome.status ?? "completed");
-        }
-        else if (terminal.kind === "cancelled") {
-            termination = String(terminal.reason ?? "cancelled");
-        }
-        else if (terminal.kind === "failed") {
-            const failure = asObject(terminal.failure);
-            termination = failure.code === "provider_recovery_exhausted"
-                ? "context_overflow"
-                : "error";
-        }
+function canonicalDoneFromTerminal(terminal) {
+    const usage = asObject(terminal.usage);
+    let termination = String(terminal.kind ?? "failed");
+    let turnsUsed = Number(usage.turns ?? 0);
+    if (terminal.kind === "agent") {
+        const result = asObject(terminal.result);
+        termination = String(result.termination ?? "completed");
+        turnsUsed = Number(result.turns_used ?? turnsUsed);
+        const finalMessage = asObject(result.final_message);
+        const pace = asObject(result.pace_decision);
         return {
-            kind: "done",
-            effectId: "",
+            kind: "done", effectId: "",
             result: {
-                termination,
-                turnsUsed,
-                totalTokensUsed: totalUsageTokens(terminal),
+                termination, turnsUsed, totalTokensUsed: totalUsageTokens(terminal),
+                ...(Object.keys(finalMessage).length > 0 ? { finalMessage: {
+                        role: String(finalMessage.role ?? "assistant"),
+                        content: String(finalMessage.content ?? ""),
+                        toolCalls: (Array.isArray(finalMessage.tool_calls) ? finalMessage.tool_calls : []).map(value => {
+                            const call = asObject(value);
+                            return { id: String(call.call_id ?? ""), name: String(call.name ?? ""), arguments: JSON.stringify(call.arguments ?? {}) };
+                        }),
+                    } } : {}),
+                ...(Object.keys(pace).length > 0 ? { paceDecision: {
+                        action: String(pace.action ?? "stop"),
+                        ...(pace.delay_ms !== undefined ? { delayMs: Number(pace.delay_ms) } : {}),
+                        reason: String(pace.reason ?? ""),
+                        ...(pace.coerced_from ? { coercedFrom: String(pace.coerced_from) } : {}),
+                    } } : {}),
             },
         };
     }
-    const published = plannedStep.disposition.effects ?? [];
-    if (published.length === 0)
+    if (terminal.kind === "workflow")
+        termination = String(asObject(terminal.outcome).status ?? "completed");
+    if (terminal.kind === "cancelled")
+        termination = String(terminal.reason ?? "cancelled");
+    if (terminal.kind === "failed")
+        termination = asObject(terminal.failure).code === "provider_recovery_exhausted" ? "context_overflow" : "error";
+    return { kind: "done", effectId: "", result: { termination, turnsUsed, totalTokensUsed: totalUsageTokens(terminal) } };
+}
+/** Adapt the additive core CurrentProjection JSON into the existing Node action surface. */
+export function canonicalActionFromProjectionJson(raw) {
+    const projection = asObject(JSON.parse(raw));
+    const state = String(projection.state ?? "idle");
+    if (state === "idle")
         return null;
-    if (published.length !== 1) {
-        throw new Error(`Node runner expects one canonical effect at a time, received ${published.length}`);
+    if (state === "terminal") {
+        return canonicalDoneFromTerminal(asObject(projection.action));
     }
-    const envelope = asObject(published[0]);
-    const effectId = String(envelope.effect_id ?? "");
-    const effect = asObject(envelope.effect);
-    if (!effectId)
-        throw new Error("canonical effect is missing effect_id");
-    switch (effect.kind) {
-        case "call_provider":
-            return {
-                kind: "call_provider",
-                effectId,
-                context: renderedContextToSdk(asObject(effect.context)),
-                tools: (Array.isArray(effect.tools) ? effect.tools : []).map(raw => {
-                    const tool = asObject(raw);
-                    return {
-                        name: String(tool.name ?? ""),
-                        description: String(tool.description ?? ""),
-                        parameters: JSON.stringify(tool.parameters ?? {}),
-                    };
-                }),
-            };
-        case "execute_tools":
-            return {
-                kind: "execute_tool",
-                effectId,
-                calls: (Array.isArray(effect.calls) ? effect.calls : []).map(raw => {
-                    const call = asObject(raw);
-                    return {
-                        id: String(call.call_id ?? ""),
-                        name: String(call.name ?? ""),
-                        arguments: JSON.stringify(call.arguments ?? {}),
-                    };
-                }),
-            };
-        case "request_approval":
-            return {
-                kind: "request_approval",
-                effectId,
-                requests: (Array.isArray(effect.requests) ? effect.requests : []).map(raw => {
-                    const request = asObject(raw);
-                    return {
-                        callId: String(request.call_id ?? ""),
-                        tool: String(request.tool_name ?? ""),
-                        arguments: JSON.stringify(request.arguments ?? {}),
-                        reason: String(request.reason ?? ""),
-                    };
-                }),
-            };
-        case "spawn_tasks":
-            return {
-                kind: "spawn_workflow",
-                effectId,
-                nodes: (Array.isArray(effect.tasks) ? effect.tasks : []).map(raw => {
-                    const task = asObject(raw);
-                    const spec = asObject(task.spec);
-                    return {
-                        agent_id: String(task.task_id ?? ""),
-                        task_id: String(task.task_id ?? ""),
-                        attempt_id: String(task.attempt_id ?? ""),
-                        launch_token: String(task.launch_token ?? ""),
-                        node_id: String(task.node_id ?? ""),
-                        goal: String(spec.goal ?? ""),
-                        role: String(spec.role ?? "custom"),
-                        isolation: String(spec.isolation ?? "shared"),
-                        context_inheritance: String(spec.context_inheritance ?? "none"),
-                        ...(spec.metadata && typeof spec.metadata === "object"
-                            ? asObject(spec.metadata)
-                            : {}),
-                    };
-                }),
-                ...(effect.budget ? { budget: asObject(effect.budget) } : {}),
-            };
-        case "preempt_tasks": {
-            const attempts = (Array.isArray(effect.attempts) ? effect.attempts : []).map(raw => {
-                const attempt = asObject(raw);
+    const action = asObject(projection.action);
+    const payload = asObject(action.payload);
+    const effectId = String(action.effect_id ?? "");
+    if (action.kind === "query_memory") {
+        return {
+            kind: "query_memory",
+            effectId,
+            query: asObject(payload.query),
+            requestedK: Number(payload.requested_k ?? 0),
+        };
+    }
+    if (action.kind === "execute_tools") {
+        return {
+            kind: "execute_tool",
+            effectId,
+            calls: (Array.isArray(payload.calls) ? payload.calls : []).map(raw => {
+                const call = asObject(raw);
                 return {
-                    task_id: String(attempt.task_id ?? ""),
-                    attempt_id: String(attempt.attempt_id ?? ""),
+                    id: String(call.call_id ?? ""),
+                    name: String(call.name ?? ""),
+                    arguments: JSON.stringify(call.arguments ?? {}),
                 };
-            });
-            return {
-                kind: "preempt_sub_agents",
-                effectId,
-                attempts,
-                agentIds: attempts.map(attempt => attempt.task_id),
-                reason: String(effect.reason ?? ""),
-            };
-        }
-        case "persist_memory":
-            return {
-                kind: "persist_memory",
-                effectId,
-                memory: asObject(effect.memory),
-            };
-        case "query_memory":
-            return {
-                kind: "query_memory",
-                effectId,
-                query: asObject(effect.query),
-                requestedK: Number(effect.requested_k ?? 0),
-            };
-        case "archive_page_out": {
-            const payload = asObject(effect.payload);
-            let archived = [];
-            try {
-                const decoded = JSON.parse(String(payload.content ?? ""));
-                if (Array.isArray(decoded)) {
-                    archived = decoded.map(value => kernelMessageToSdk(asObject(value)));
-                }
-            }
-            catch {
-                // Persistence still uses the opaque body and digest. Only optional presentation-side
-                // summarization is skipped if the archived message batch cannot be decoded.
-            }
-            const compressed = (plannedStep.observations ?? [])
-                .find(observation => observation.kind === "compressed");
-            const pressureAction = compressed ? String(compressed.action ?? "") : "";
-            return {
-                kind: "archive_page_out",
-                effectId,
-                handleId: String(effect.handle_id ?? ""),
-                payload,
-                archived,
-                ...(pressureAction ? { action: pressureAction } : {}),
-                ...(compressed?.summary ? { summary: String(compressed.summary) } : {}),
-                ...(pressureAction
-                    ? {
-                        tier: ["context_collapse", "auto_compact"].includes(pressureAction)
-                            ? "semantic"
-                            : "durable",
-                    }
-                    : {}),
-            };
+            }),
+        };
+    }
+    if (action.kind === "call_provider") {
+        const context = asObject(payload.context);
+        return {
+            kind: "call_provider",
+            effectId,
+            context: renderedContextToSdk(context),
+            tools: (Array.isArray(payload.tools) ? payload.tools : []).map(raw => {
+                const tool = asObject(raw);
+                return {
+                    name: String(tool.name ?? ""),
+                    description: String(tool.description ?? ""),
+                    parameters: JSON.stringify(tool.parameters ?? {}),
+                };
+            }),
+        };
+    }
+    if (action.kind === "request_approval") {
+        return {
+            kind: "request_approval",
+            effectId,
+            requests: (Array.isArray(payload.requests) ? payload.requests : []).map(raw => {
+                const request = asObject(raw);
+                return {
+                    callId: String(request.call_id ?? ""),
+                    tool: String(request.tool_name ?? ""),
+                    arguments: JSON.stringify(request.arguments ?? {}),
+                    reason: String(request.reason ?? ""),
+                };
+            }),
+        };
+    }
+    if (action.kind === "load_payload") {
+        return {
+            kind: "load_payload",
+            effectId,
+            handleId: String(payload.handle_id ?? ""),
+            payloadRef: String(payload.payload_ref ?? ""),
+        };
+    }
+    if (action.kind === "evaluate_milestone") {
+        const request = asObject(payload.request);
+        return {
+            kind: "evaluate_milestone",
+            effectId,
+            phaseId: String(request.phase_id ?? ""),
+            criteria: [],
+            requiredEvidence: [],
+        };
+    }
+    if (action.kind === "spawn_tasks") {
+        return {
+            kind: "spawn_workflow",
+            effectId,
+            nodes: (Array.isArray(payload.tasks) ? payload.tasks : []).map(raw => {
+                const task = asObject(raw);
+                const spec = asObject(task.spec);
+                return {
+                    agent_id: String(task.task_id ?? ""), task_id: String(task.task_id ?? ""),
+                    attempt_id: String(task.attempt_id ?? ""), launch_token: String(task.launch_token ?? ""),
+                    node_id: String(task.node_id ?? ""), goal: String(spec.goal ?? ""),
+                    role: String(spec.role ?? "custom"), isolation: String(spec.isolation ?? "shared"),
+                    context_inheritance: String(spec.context_inheritance ?? "none"),
+                    ...(spec.metadata && typeof spec.metadata === "object" ? asObject(spec.metadata) : {}),
+                };
+            }),
+            ...(payload.budget ? { budget: asObject(payload.budget) } : {}),
+        };
+    }
+    if (action.kind === "preempt_tasks") {
+        const attempts = (Array.isArray(payload.attempts) ? payload.attempts : []).map(raw => {
+            const attempt = asObject(raw);
+            return { task_id: String(attempt.task_id ?? ""), attempt_id: String(attempt.attempt_id ?? "") };
+        });
+        return { kind: "preempt_sub_agents", effectId, attempts, agentIds: attempts.map(a => a.task_id), reason: String(payload.reason ?? "") };
+    }
+    if (action.kind === "persist_memory") {
+        return { kind: "persist_memory", effectId, memory: asObject(payload.memory) };
+    }
+    if (action.kind === "archive_page_out") {
+        const archivePayload = asObject(payload.payload);
+        let archived = [];
+        try {
+            const decoded = JSON.parse(String(archivePayload.content ?? ""));
+            if (Array.isArray(decoded))
+                archived = decoded.map(value => kernelMessageToSdk(asObject(value)));
         }
-        case "load_payload":
-            return {
-                kind: "load_payload",
-                effectId,
-                handleId: String(effect.handle_id ?? ""),
-                payloadRef: String(effect.payload_ref ?? ""),
-            };
-        case "evaluate_milestone": {
-            const request = asObject(effect.request);
-            return {
-                kind: "evaluate_milestone",
-                effectId,
-                phaseId: String(request.phase_id ?? ""),
-                criteria: [],
-                requiredEvidence: [],
-            };
+        catch {
+            // The opaque archive payload remains authoritative even when presentation decoding fails.
         }
-        default:
-            return {
-                kind: "unsupported_effect",
-                effectId,
-                effectKind: String(effect.kind),
-            };
+        return {
+            kind: "archive_page_out",
+            effectId,
+            handleId: String(payload.handle_id ?? ""),
+            payload: {
+                content: String(archivePayload.content ?? ""),
+                digest: String(archivePayload.digest ?? ""),
+                original_size: String(archivePayload.original_size ?? "0"),
+                ...(archivePayload.preview ? { preview: String(archivePayload.preview) } : {}),
+            },
+            archived,
+        };
     }
+    return {
+        kind: "unsupported_effect",
+        effectId,
+        effectKind: String(action.kind ?? ""),
+    };
 }
 export class CanonicalKernelRejectedError extends Error {
     fault;
@@ -1178,6 +1125,16 @@ export class CanonicalRunnerRuntime {
                             throw new Error("canonical observation is missing kind");
                         this.hostObservations.push({ ...raw, kind });
                     }
+                    // §7.11 · a committed step that publishes effects is a fact worth recording in the
+                    // host event log: the journal stores only a digest of the step, so this manifest is
+                    // what makes the published effect ids + kinds recoverable post-hoc without replaying.
+                    const published = JSON.parse(this.host.kernel.publishedEffectsManifestJson(JSON.stringify(transition.plannedStep)));
+                    if (published.length > 0) {
+                        this.hostObservations.push({
+                            kind: "step_published_effects",
+                            effects: published,
+                        });
+                    }
                     if (transition.checkpointAdvice) {
                         this.hostObservations.push({
                             kind: "checkpoint_advised",
@@ -1191,7 +1148,7 @@ export class CanonicalRunnerRuntime {
                         });
                     }
                 }
-                this.lastAction = canonicalActionFromPlannedStep(transition.plannedStep);
+                this.lastAction = canonicalActionFromProjectionJson(this.host.kernel.projectPlannedStepJson(JSON.stringify(transition.plannedStep)));
             }
             if (this.lastAction?.kind !== "unsupported_effect")
                 return this.lastAction;
@@ -1199,16 +1156,7 @@ export class CanonicalRunnerRuntime {
         }
     }
     currentAction() {
-        const terminal = this.host.kernel.terminalJson();
-        if (terminal) {
-            return canonicalActionFromPlannedStep({
-                disposition: { kind: "terminal", terminal: JSON.parse(terminal) },
-            });
-        }
-        const effects = this.pendingEffects();
-        return canonicalActionFromPlannedStep({
-            disposition: { kind: "effects", effects },
-        });
+        return canonicalActionFromProjectionJson(this.host.kernel.currentProjectionJson());
     }
     pendingEffects() {
         return JSON.parse(this.host.kernel.pendingEffectsJson());

package/dist/runtime/execution-evidence.d.ts

@@ -0,0 +1,116 @@
+/**
+ * P4 (0.2.64 Execution Evidence Plane): the host-side object model connecting a kernel-minted
+ * effect to the real provider execution it drove — ModelInvocation / ProviderAttempt /
+ * ResolvedProviderRoute / UsageAccountingPolicy. Everything here is L2 host evidence
+ * (B7): it lands in SessionLog for cross-verification against the journal (C6/C8) and is
+ * NEVER fed back as kernel input (B4/DEC-2 discipline: wall-clock and wire facts stay host-side).
+ *
+ * Kernel ABI is untouched — the kernel projection of an invocation outcome remains the
+ * existing ProviderCompleted/HostEffectFailure shapes (D2).
+ */
+import type { ProviderUsage, ProviderWireEvidence, UsageEvent } from "../types.js";
+import { type NormalizedProviderUsage, type ResolvedProviderRoute } from "../providers/request-plan.js";
+/** Canonical stop-reason vocabulary already carried on the wire usage frame (types.ts). */
+export type CanonicalStopReason = NonNullable<UsageEvent["stopReason"]>;
+/**
+ * P4 §1.1: one logical model call = the fact-connected chain of CallProvider effects the
+ * kernel walked to obtain one turn of model output. Derived identity, zero minting:
+ * `invocationId` IS the first effect's effect_id. Authority = journal; the SessionLog
+ * projection (`llm_completed.invocation_id`) is evidence only.
+ */
+export interface ModelInvocation {
+    invocationId: string;
+    turn: number;
+    /** Every effect_id on the chain, in order. Length 1 = first attempt succeeded. */
+    effectChain: string[];
+    outcome?: InvocationOutcome;
+}
+/** P4 §1.4: the invocation's terminal projection. */
+export interface InvocationOutcome {
+    invocationId: string;
+    /** The effect the kernel adopted as the outcome (the successful one). */
+    selectedEffectId: string;
+    stopReason?: CanonicalStopReason;
+    /** Absent on a failed chain (nothing settled). */
+    settlement?: UsageSettlement;
+}
+export type ProviderAttemptStatus = "success" | "transport_exhausted" | "aborted" | "rejected";
+/**
+ * P4 §1.2: one effect's execution against one route, one physical attempt. The kernel-minted
+ * `effectId` is the primary key (H7 — no parallel id minting). Transport-ladder rungs are
+ * summarized as a count plus the final error class; rung-level evidence belongs to adapter
+ * debug logs, not SessionLog.
+ */
+export interface ProviderAttempt {
+    effectId: string;
+    /** Failover sequence within one effect execution (1-based). Always 1 today (P4 §0.2). */
+    attemptSeq: number;
+    route: ResolvedProviderRoute;
+    /** → ProviderRequestPlan.fingerprint (G2). */
+    requestFingerprint: string;
+    status: ProviderAttemptStatus;
+    transportRungs: number;
+    /** classifyProviderError's class, never the raw vendor text (B1 spirit). */
+    lastErrorClass?: string;
+    /** Host wall-clock, pure evidence, never kernel input (DEC-2 discipline). */
+    startedAtMs: number;
+    finishedAtMs: number;
+    /** Full measurement fields (P4 §2); only the settlement crosses the kernel boundary (B4). */
+    usage?: NormalizedProviderUsage;
+    wireEvidence?: ProviderWireEvidence;
+}
+/**
+ * The SessionLog wire payload of a ProviderAttempt (P4 §3): the §1.2 fields flattened into
+ * the event, snake_case per SessionLog convention. Nested objects keep their native shape
+ * (same convention as `prompt_measured.measurement`).
+ */
+export interface ProviderAttemptRecord {
+    effect_id: string;
+    attempt_seq: number;
+    route: ResolvedProviderRoute;
+    request_fingerprint: string;
+    status: ProviderAttemptStatus;
+    transport_rungs: number;
+    last_error_class?: string;
+    started_at_ms: number;
+    finished_at_ms: number;
+    usage?: NormalizedProviderUsage;
+    wire_evidence?: ProviderWireEvidence;
+    /** P4 §2.1: the accounting policy this attempt's settlement was/will be derived with —
+     *  pinned on the attempt so settlement is deterministically recomputable from
+     *  (measurement, policy_id). */
+    accounting_policy_id?: string;
+}
+export declare function providerAttemptToRecord(attempt: ProviderAttempt, accountingPolicyId?: string): ProviderAttemptRecord;
+/**
+ * P4 §2: the only two numbers that cross the kernel boundary (B4). Field names match the
+ * existing ResolveEffect wire shape — this is what the runner already feeds the kernel as
+ * `observed_input_tokens` / `observed_output_tokens`.
+ */
+export interface UsageSettlement {
+    observed_input_tokens: number;
+    observed_output_tokens: number;
+}
+/**
+ * P4 §2.1: the named, pinnable, replayable policy turning a measurement into a settlement.
+ * `settle` must be a pure function of the measurement — given (usage, policyId) any auditor
+ * recomputes the identical settlement.
+ */
+export interface UsageAccountingPolicy {
+    policyId: string;
+    settle(usage: NormalizedProviderUsage): UsageSettlement;
+}
+/**
+ * The default policy = today's implicit runner behavior exactly (full input footprint + full
+ * output footprint — the two numbers the runner has always fed `observed_*`). P4 changes no
+ * default numbers; it only makes the conversion a named object. The date stamp is the
+ * policy's identity: any future semantics change MUST ship under a new policyId.
+ */
+export declare const FULL_FOOTPRINT_USAGE_ACCOUNTING_POLICY: UsageAccountingPolicy;
+/**
+ * Defensive measurement assembly for the attempt evidence path: an invalid frame (cache
+ * subsets exceeding input, etc.) degrades to NO measurement instead of breaking the run —
+ * evidence is never worth a run failure, and the settlement falls back to the raw counts.
+ * Telemetry fields normalizeProviderUsage drops are re-attached so `usage` stays full-field.
+ */
+export declare function tryNormalizeProviderUsage(usage: ProviderUsage): NormalizedProviderUsage | undefined;

package/dist/runtime/execution-evidence.js

@@ -0,0 +1,51 @@
+import { normalizeProviderUsage, } from "../providers/request-plan.js";
+export function providerAttemptToRecord(attempt, accountingPolicyId) {
+    return {
+        effect_id: attempt.effectId,
+        attempt_seq: attempt.attemptSeq,
+        route: attempt.route,
+        request_fingerprint: attempt.requestFingerprint,
+        status: attempt.status,
+        transport_rungs: attempt.transportRungs,
+        ...(attempt.lastErrorClass !== undefined ? { last_error_class: attempt.lastErrorClass } : {}),
+        started_at_ms: attempt.startedAtMs,
+        finished_at_ms: attempt.finishedAtMs,
+        ...(attempt.usage !== undefined ? { usage: attempt.usage } : {}),
+        ...(attempt.wireEvidence !== undefined ? { wire_evidence: attempt.wireEvidence } : {}),
+        ...(accountingPolicyId !== undefined ? { accounting_policy_id: accountingPolicyId } : {}),
+    };
+}
+/**
+ * The default policy = today's implicit runner behavior exactly (full input footprint + full
+ * output footprint — the two numbers the runner has always fed `observed_*`). P4 changes no
+ * default numbers; it only makes the conversion a named object. The date stamp is the
+ * policy's identity: any future semantics change MUST ship under a new policyId.
+ */
+export const FULL_FOOTPRINT_USAGE_ACCOUNTING_POLICY = {
+    policyId: "deepstrike.full-footprint@2026-09-15",
+    settle(usage) {
+        return {
+            observed_input_tokens: usage.inputTokens,
+            observed_output_tokens: usage.outputTokens,
+        };
+    },
+};
+/**
+ * Defensive measurement assembly for the attempt evidence path: an invalid frame (cache
+ * subsets exceeding input, etc.) degrades to NO measurement instead of breaking the run —
+ * evidence is never worth a run failure, and the settlement falls back to the raw counts.
+ * Telemetry fields normalizeProviderUsage drops are re-attached so `usage` stays full-field.
+ */
+export function tryNormalizeProviderUsage(usage) {
+    try {
+        const normalized = normalizeProviderUsage(usage);
+        return {
+            ...normalized,
+            ...(usage.cacheTelemetryStatus !== undefined ? { cacheTelemetryStatus: usage.cacheTelemetryStatus } : {}),
+            ...(usage.cacheTelemetrySource !== undefined ? { cacheTelemetrySource: usage.cacheTelemetrySource } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/runtime/kernel-doctor.d.ts

@@ -0,0 +1,36 @@
+import type { CanonicalKernelInstance } from "../kernel.js";
+import type { KernelJournal } from "./kernel-journal.js";
+/**
+ * What a journal inspection knows: whether the operation restores, and — when it does not — which
+ * record is the first this binary cannot replay. The effect manifest (which effects each step
+ * published) lives in the host event log via the `step_published_effects` observation, not here:
+ * a journal stores only each record's input and digests, never the step it produced (§8.1).
+ */
+export interface KernelJournalDiagnosis {
+    operationId: string;
+    recordCount: number;
+    /** True when `restore()` replayed the whole journal and verified every step digest. */
+    restorable: boolean;
+    /**
+     * The `step_seq` of the first record whose replay diverged from the durable digest, when known.
+     * The restore failure message names this step; a fault before any record replays leaves it null.
+     */
+    divergenceStep: number | null;
+    divergenceReason: string | null;
+    /** The operation's terminal, only when the journal restored cleanly. */
+    terminal: Record<string, unknown> | undefined;
+    /** Pending effects at the head, only when the journal restored cleanly. */
+    pendingEffects: Array<{
+        effect_id: string;
+        kind: string;
+    }>;
+}
+/**
+ * Inspect a durable journal without committing anything: replay it through the kernel and report
+ * whether it still restores. This turns a "silent brick" — an operation whose journal was appended
+ * but whose step can no longer be re-derived by this binary — into an actionable diagnosis: which
+ * record diverges, and what the head still holds if it does not.
+ *
+ * Nothing is mutated; the same journal can be diagnosed repeatedly and then restored normally.
+ */
+export declare function diagnoseKernelJournal(kernel: CanonicalKernelInstance, journal: KernelJournal, operationId: string): Promise<KernelJournalDiagnosis>;