@deepstrike/sdk 0.2.62 → 0.2.64

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?: ModelUsageSettlement;
+}
+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 ModelUsageSettlement {
+    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): ModelUsageSettlement;
+}
+/**
+ * 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-step.d.ts

@@ -1,7 +1,9 @@
 import type { EntropySample, Message, RenderedContext, TaskUpdate, ToolCall, ToolResult, ToolSchema } from "../types.js";
 import type { SkillMetadata } from "../skills/loader.js";
 import type { RollbackReason } from "./session-log.js";
+export declare const CANONICAL_CONTENT_PARTS_PREFIX = "[[deepstrike-content-parts]]";
 export declare function encodeCanonicalContentParts(parts: unknown[]): string;
+export declare function decodeCanonicalContentParts(content: string): Array<Record<string, unknown>> | undefined;
 export interface PaceDecision {
     action: "continue" | "sleep" | "stop";
     delayMs?: number;

package/dist/runtime/kernel-step.js

@@ -1,8 +1,8 @@
-const CANONICAL_CONTENT_PARTS_PREFIX = "[[deepstrike-content-parts]]";
+export const CANONICAL_CONTENT_PARTS_PREFIX = "[[deepstrike-content-parts]]";
 export function encodeCanonicalContentParts(parts) {
     return `${CANONICAL_CONTENT_PARTS_PREFIX}${Buffer.from(JSON.stringify(parts)).toString("base64url")}`;
 }
-function decodeCanonicalContentParts(content) {
+export function decodeCanonicalContentParts(content) {
     if (!content.startsWith(CANONICAL_CONTENT_PARTS_PREFIX))
         return undefined;
     try {

package/dist/runtime/runner.d.ts

@@ -13,6 +13,7 @@ export declare function stableSemanticArchiveName(effectId: string): string;
 import { type SubAgentOrchestrator } from "./sub-agent-orchestrator.js";
 import { type ReducerRegistry } from "./reducers.js";
 import { type GovernancePolicy } from "../governance.js";
+import { type UsageAccountingPolicy } from "./execution-evidence.js";
 import { type NativeOsProfile, type OsProfileId, type SignalPolicy } from "./os-profile.js";
 import { PayloadStore } from "./payload-store.js";
 import type { BackgroundTaskErrorHandler } from "./reliability.js";
@@ -176,6 +177,12 @@ export interface RuntimeOptions {
     signalPolicy?: SignalPolicy;
     /** Provider-envelope overhead plus output and safety reserves journaled before start. */
     promptBudget?: PromptBudget;
+    /**
+     * P4-S2: the measurement→settlement conversion policy. Absent ⇒ the default full-footprint
+     * policy — byte-identical numbers to what the runner has always fed `observed_*`; the policy
+     * only makes the conversion named, pinnable on `provider_attempt`, and replayable.
+     */
+    usageAccountingPolicy?: UsageAccountingPolicy;
     /** Stable replayable context behavior; SDK ratios are normalized to integer ppm on the ABI wire. */
     contextPolicy?: ContextPolicyOverrides;
     /** Deterministic DAG scheduling policy installed atomically through ConfigureRun. */
@@ -403,6 +410,16 @@ export declare class RuntimeRunner {
     private readonly composedSystemPrompt;
     /** H1.2: present only when `opts.nudges` is non-empty; else null and the append funnel is untouched. */
     private readonly nudgeEngine;
+    /** P4-S1: the run's resolved provider route, assembled once at construction (P4 §0.2 — the
+     *  provider is fixed for the run today; every attempt references this same route object). */
+    private readonly providerRoute;
+    /** P4-S2: measurement→settlement policy; default = the exact implicit behavior (numbers unchanged). */
+    private readonly usageAccountingPolicy;
+    /** P4 §1.1: the active invocation's derived identity = its chain's FIRST effect_id. Tracked
+     *  across kernel-driven provider retries (a provider_error commit arms `providerRetryPending`;
+     *  the next call_provider adopts the pending invocation instead of opening a new one). */
+    private activeProviderInvocationId;
+    private providerRetryPending;
     constructor(opts: RuntimeOptions);
     /** Host configuration (for coordinator / sub-agent spawn). */
     get hostOptions(): RuntimeOptions;
@@ -412,6 +429,13 @@ export declare class RuntimeRunner {
     private commitKernelAction;
     private startKernelAgent;
     private payloadStore;
+    /**
+     * P4-S1 (G1): land one provider_attempt evidence record per effect execution. Pure host
+     * evidence (B7) — appended AFTER the transport fact exists (success/failure/abort), never
+     * consulted for kernel input. The accounting policy id pins only when a measurement exists,
+     * so (usage, policy_id) deterministically recomputes the settlement that crossed the wire.
+     */
+    private appendProviderAttempt;
     private persistMemoryToStore;
     private retrieveMemoryFromStore;
     /**

package/dist/runtime/runner.js

@@ -24,7 +24,8 @@ import { extractJsonValue, schemaInstruction, schemaRetryInstruction, validateAg
 import { resolveReducer } from "./reducers.js";
 import { loopInstruction, classifyInstruction, judgeGoal, dependencyOutputsNote, extractClassifyBranch, extractJudgeWinner, } from "./workflow-control-flow.js";
 import { governancePolicyToKernelEvent, governanceFilterSchema } from "../governance.js";
-import { createProviderRequestPlanForProvider, estimateProviderPromptTokens, measurementForPlan, recordPromptMeasurement, } from "../providers/request-plan.js";
+import { createProviderRequestPlanForProvider, estimateProviderPromptTokens, measurementForPlan, recordPromptMeasurement, resolveProviderRoute, } from "../providers/request-plan.js";
+import { FULL_FOOTPRINT_USAGE_ACCOUNTING_POLICY, providerAttemptToRecord, tryNormalizeProviderUsage, } from "./execution-evidence.js";
 import { kernelObservationToSessionEvent } from "./kernel-event-log.js";
 import { assertNativeProfile } from "./os-profile.js";
 import { PayloadStore } from "./payload-store.js";
@@ -164,6 +165,16 @@ export class RuntimeRunner {
     composedSystemPrompt;
     /** H1.2: present only when `opts.nudges` is non-empty; else null and the append funnel is untouched. */
     nudgeEngine;
+    /** P4-S1: the run's resolved provider route, assembled once at construction (P4 §0.2 — the
+     *  provider is fixed for the run today; every attempt references this same route object). */
+    providerRoute;
+    /** P4-S2: measurement→settlement policy; default = the exact implicit behavior (numbers unchanged). */
+    usageAccountingPolicy;
+    /** P4 §1.1: the active invocation's derived identity = its chain's FIRST effect_id. Tracked
+     *  across kernel-driven provider retries (a provider_error commit arms `providerRetryPending`;
+     *  the next call_provider adopts the pending invocation instead of opening a new one). */
+    activeProviderInvocationId;
+    providerRetryPending = false;
     constructor(opts) {
         this.opts = opts;
         const schemaAttempts = opts.workflowSchemaValidationAttempts ?? 2;
@@ -175,6 +186,8 @@ export class RuntimeRunner {
         if (opts.memoryPolicy)
             memoryPolicyToKernel(opts.memoryPolicy);
         this.composedSystemPrompt = composeSystemPrompt(opts.systemPrompt, opts.instructions);
+        this.providerRoute = resolveProviderRoute(opts.provider);
+        this.usageAccountingPolicy = opts.usageAccountingPolicy ?? FULL_FOOTPRINT_USAGE_ACCOUNTING_POLICY;
         if (opts.enableDiagnosticsDashboard) {
             const originalAppend = opts.sessionLog.append.bind(opts.sessionLog);
             opts.sessionLog.append = async (sessionId, event) => {
@@ -230,6 +243,18 @@ export class RuntimeRunner {
         this.fallbackPayloadStore ??= new PayloadStore();
         return this.fallbackPayloadStore;
     }
+    /**
+     * P4-S1 (G1): land one provider_attempt evidence record per effect execution. Pure host
+     * evidence (B7) — appended AFTER the transport fact exists (success/failure/abort), never
+     * consulted for kernel input. The accounting policy id pins only when a measurement exists,
+     * so (usage, policy_id) deterministically recomputes the settlement that crossed the wire.
+     */
+    async appendProviderAttempt(sessionId, attempt) {
+        await this.opts.sessionLog.append(sessionId, {
+            kind: "provider_attempt",
+            ...providerAttemptToRecord(attempt, attempt.usage ? this.usageAccountingPolicy.policyId : undefined),
+        });
+    }
     async persistMemoryToStore(memory, agentId) {
         if (!this.opts.memoryStore)
             throw new Error("memory persistence requires memoryStore");
@@ -754,6 +779,7 @@ export class RuntimeRunner {
                     goal: `workflow:${spec.nodes.length} nodes`,
                     criteria: [],
                     agent_id: this.opts.agentId,
+                    route: this.providerRoute,
                 });
                 await this.initializeWorkflowKernel(sessionId, runId, groupBudgetScope);
             }
@@ -1204,6 +1230,7 @@ export class RuntimeRunner {
                 agent_id: this.opts.agentId,
                 system_prompt: this.composedSystemPrompt,
                 ...(attachments ? { attachments } : {}),
+                route: this.providerRoute,
             });
         }
         yield* this.execute(req.sessionId, req.goal, req.criteria ?? [], req.extensions, prior.length > 0 ? prior : undefined, midRun, attachments, runId);
@@ -1233,7 +1260,10 @@ export class RuntimeRunner {
         yield* this.execute(sessionId, start.goal, start.criteria, extensions, events, true, start.attachments, start.run_id);
     }
     /** Execute a kernel-owned approval effect and return the correlated decision lists. */
-    async resolveApprovalRequests(requests, runtime, sessionId) {
+    async resolveApprovalRequests(requests, runtime, sessionId, 
+    /** P3-S2 (G4): the request_approval effect's id — pinned on the denial's tool_completed
+     *  so the denial evidence joins the journal effect chain like an executed tool's does. */
+    effectId) {
         const approved = [];
         const denied = [];
         const events = [];
@@ -1306,6 +1336,7 @@ export class RuntimeRunner {
                             error_kind: "governance_denied",
                             content: { blocks: [{ type: "text", text: `permission denied: ${denyReason}` }] },
                         }],
+                    ...(effectId !== undefined ? { effect_id: effectId } : {}),
                 });
             }
         }
@@ -1319,6 +1350,8 @@ export class RuntimeRunner {
         this.pendingPageOutArchives = [];
         this.activePageOutArchive = undefined;
         this.currentSessionId = sessionId;
+        this.activeProviderInvocationId = undefined;
+        this.providerRetryPending = false;
         if (this.opts.enableDiagnosticsDashboard) {
             this.dashboard = new KernelPrimitivesDashboard(sessionId);
         }
@@ -1557,6 +1590,18 @@ export class RuntimeRunner {
                         break;
                     if (action.kind === "call_provider") {
                         const providerEffectId = action.effectId;
+                        // P4 §1.1: invocation identity is derived, never minted — the chain's FIRST effect_id.
+                        // A provider_error commit armed `providerRetryPending`, so this effect CONTINUES the
+                        // pending invocation; otherwise it opens a new one. The chain itself lives in the
+                        // journal (each hop a Failed resolution input → new effect); this is the SessionLog
+                        // evidence projection of it.
+                        if (!this.providerRetryPending || this.activeProviderInvocationId === undefined) {
+                            this.activeProviderInvocationId = providerEffectId;
+                        }
+                        this.providerRetryPending = false;
+                        const invocationId = this.activeProviderInvocationId;
+                        // Host wall-clock, pure evidence (B7/DEC-2): never crosses into kernel input.
+                        const attemptStartedAtMs = Date.now();
                         const finalToolCalls = [];
                         let finalText = "";
                         // I5: governance schema-level pre-filter. When a declarative GovernancePolicy is loaded
@@ -1588,6 +1633,9 @@ export class RuntimeRunner {
                         let turnCacheTelemetrySource;
                         let turnCacheReadBySlot;
                         let turnStopReason;
+                        // P4 §2: the raw postflight provider usage frame, kept whole so the attempt's
+                        // measurement carries full fields (only the settlement crosses the kernel boundary, B4).
+                        let turnProviderUsage;
                         const providerPlan = createProviderRequestPlanForProvider(this.opts.provider, context, tools, ext);
                         const recorded = measurementForPlan(providerPlan, recordedMeasurements.get(providerPlan.fingerprint));
                         let promptMeasurement = recorded;
@@ -1614,6 +1662,7 @@ export class RuntimeRunner {
                                 kind: "prompt_measured",
                                 turn: runtime.turn(),
                                 measurement: promptMeasurement,
+                                effect_id: providerEffectId,
                             });
                         }
                         const reservedPromptTokens = (this.opts.promptBudget?.promptOverheadTokens ?? 0)
@@ -1626,6 +1675,23 @@ export class RuntimeRunner {
                             && promptMeasurement.source.kind !== "heuristic"
                             && promptMeasurement.inputTokens + reservedPromptTokens > this.opts.maxTokens;
                         if (context.budgetOverflow || measuredOverflow) {
+                            // P4 §1.2: blocked BEFORE any transport — zero rungs, status rejected. The
+                            // fingerprint still binds the would-be request to its prompt_measured record (G2).
+                            await this.appendProviderAttempt(sessionId, {
+                                effectId: providerEffectId,
+                                attemptSeq: 1,
+                                route: this.providerRoute,
+                                requestFingerprint: providerPlan.fingerprint,
+                                status: "rejected",
+                                transportRungs: 0,
+                                lastErrorClass: "context_overflow",
+                                startedAtMs: attemptStartedAtMs,
+                                finishedAtMs: Date.now(),
+                                wireEvidence: {
+                                    protocol: this.providerRoute.protocol,
+                                    request_fingerprint: providerPlan.fingerprint,
+                                },
+                            });
                             action = await this.commitKernelAction(runtime, this.pendingObservations, {
                                 kind: "provider_error",
                                 effect_id: providerEffectId,
@@ -1633,6 +1699,7 @@ export class RuntimeRunner {
                                 error_kind: "context_overflow",
                                 retryable: false,
                             });
+                            this.providerRetryPending = action.kind === "call_provider";
                             continue;
                         }
                         const abortSignal = this.abortController?.signal;
@@ -1648,6 +1715,7 @@ export class RuntimeRunner {
                                     turnTokens = usageEvt.totalTokens;
                                     turnInputTokens = usageEvt.inputTokens ?? 0;
                                     turnOutputTokens = usageEvt.outputTokens ?? 0;
+                                    turnProviderUsage = usageEvt.providerUsage ?? turnProviderUsage;
                                     // P0-C: capture the prompt-cache split for the tool-gating hit-rate baseline.
                                     turnCacheReadTokens = usageEvt.cacheReadInputTokens ?? 0;
                                     turnCacheCreationTokens = usageEvt.cacheCreationInputTokens ?? 0;
@@ -1679,6 +1747,7 @@ export class RuntimeRunner {
                                                 source: postflight.source,
                                                 confidence: postflight.confidence,
                                             },
+                                            effect_id: providerEffectId,
                                         });
                                     }
                                     // Phase 4: stop_reason drives the kernel's max-output-tokens recovery. The closing
@@ -1706,6 +1775,26 @@ export class RuntimeRunner {
                                 const provider = this.opts.provider.descriptor?.().provider ?? "unknown";
                                 const providerError = classifyProviderError(provider, err);
                                 const message = providerError.message;
+                                // P4 §1.2: the transport ladder is exhausted — one attempt record, rung count from
+                                // provider telemetry (1 on the single-shot stream path), error CLASS only (B1:
+                                // never the raw vendor text).
+                                const telemetry = this.opts.provider.peekTransportTelemetry?.();
+                                await this.appendProviderAttempt(sessionId, {
+                                    effectId: providerEffectId,
+                                    attemptSeq: 1,
+                                    route: this.providerRoute,
+                                    requestFingerprint: providerPlan.fingerprint,
+                                    status: "transport_exhausted",
+                                    transportRungs: telemetry?.rungs ?? 1,
+                                    lastErrorClass: providerError.kind,
+                                    startedAtMs: attemptStartedAtMs,
+                                    finishedAtMs: Date.now(),
+                                    wireEvidence: {
+                                        protocol: this.providerRoute.protocol,
+                                        request_fingerprint: providerPlan.fingerprint,
+                                        ...(telemetry?.responseId !== undefined ? { response_id: telemetry.responseId } : {}),
+                                    },
+                                });
                                 // Reactive recovery is now a kernel decision. Forward the raw provider error and
                                 // dispatch whatever the kernel returns: `call_provider` to retry with a freshly
                                 // compacted context, or `done` to terminate with an honest `ContextOverflow`. The
@@ -1719,6 +1808,9 @@ export class RuntimeRunner {
                                     message,
                                     ...providerErrorEventFields(providerError),
                                 });
+                                // P4 §1.1: a kernel-recovered retry CONTINUES this invocation (the journal holds the
+                                // causation hop); a terminal closes it.
+                                this.providerRetryPending = action.kind === "call_provider";
                                 // Withholding (query.ts parity): surface the raw provider error only when the kernel
                                 // could NOT recover (it returned a terminal). On a recovered retry (`call_provider`)
                                 // the error stays hidden, so embedders that terminate on `error` events don't see a
@@ -1731,6 +1823,23 @@ export class RuntimeRunner {
                         }
                         // Do not commit partial provider output after host cancellation.
                         if (abortSignal?.aborted) {
+                            // P4 §1.2: host cancellation mid-stream — the attempt is evidence too.
+                            const telemetry = this.opts.provider.peekTransportTelemetry?.();
+                            await this.appendProviderAttempt(sessionId, {
+                                effectId: providerEffectId,
+                                attemptSeq: 1,
+                                route: this.providerRoute,
+                                requestFingerprint: providerPlan.fingerprint,
+                                status: "aborted",
+                                transportRungs: telemetry?.rungs ?? 1,
+                                startedAtMs: attemptStartedAtMs,
+                                finishedAtMs: Date.now(),
+                                wireEvidence: {
+                                    protocol: this.providerRoute.protocol,
+                                    request_fingerprint: providerPlan.fingerprint,
+                                    ...(telemetry?.responseId !== undefined ? { response_id: telemetry.responseId } : {}),
+                                },
+                            });
                             action = await this.commitKernelAction(runtime, this.pendingObservations, {
                                 kind: "cancel_operation",
                                 reason: this.cancellationReason ?? "user",
@@ -1762,12 +1871,37 @@ export class RuntimeRunner {
                             toolCalls: canonicalToolCalls,
                             tokenCount: turnOutputTokens || turnTokens || undefined,
                         };
+                        // P4 §2: assemble the measurement from the exact numbers that cross the boundary today
+                        // (inputTokens/outputTokens turn counters), enriched with the raw provider frame's cache
+                        // split and reasoning fields. An invalid frame degrades to no measurement (evidence
+                        // never breaks a run); the settlement then falls back to the raw counts below.
+                        const attemptUsage = (turnInputTokens > 0 || turnOutputTokens > 0)
+                            ? tryNormalizeProviderUsage({
+                                inputTokens: turnInputTokens,
+                                outputTokens: turnOutputTokens,
+                                ...(turnProviderUsage?.cacheReadInputTokens !== undefined
+                                    ? { cacheReadInputTokens: turnProviderUsage.cacheReadInputTokens }
+                                    : turnCacheReadTokens > 0 ? { cacheReadInputTokens: turnCacheReadTokens } : {}),
+                                ...(turnProviderUsage?.cacheCreationInputTokens !== undefined
+                                    ? { cacheCreationInputTokens: turnProviderUsage.cacheCreationInputTokens }
+                                    : turnCacheCreationTokens > 0 ? { cacheCreationInputTokens: turnCacheCreationTokens } : {}),
+                                ...(turnProviderUsage?.reasoningTokens !== undefined
+                                    ? { reasoningTokens: turnProviderUsage.reasoningTokens } : {}),
+                                cacheTelemetryStatus: turnCacheTelemetryStatus,
+                                ...(turnCacheTelemetrySource !== undefined
+                                    ? { cacheTelemetrySource: turnCacheTelemetrySource } : {}),
+                            })
+                            : undefined;
+                        const settlement = attemptUsage ? this.usageAccountingPolicy.settle(attemptUsage) : undefined;
                         const providerEvent = {
                             kind: "provider_result",
                             effect_id: providerEffectId,
                             message: messageToKernelMessage(assistantMessage),
-                            ...(turnInputTokens > 0 ? { observed_input_tokens: turnInputTokens } : {}),
-                            ...(turnOutputTokens > 0 ? { observed_output_tokens: turnOutputTokens } : {}),
+                            // P4-S2: observed_* now comes from the pinned policy's settlement of the measurement.
+                            // Under the default full-footprint policy these are provably the numbers the runner
+                            // has always fed (inputTokens/outputTokens verbatim under the same >0 gates).
+                            ...(turnInputTokens > 0 ? { observed_input_tokens: settlement?.observed_input_tokens ?? turnInputTokens } : {}),
+                            ...(turnOutputTokens > 0 ? { observed_output_tokens: settlement?.observed_output_tokens ?? turnOutputTokens } : {}),
                             ...(turnStopReason ? { stop_reason: turnStopReason } : {}),
                         };
                         if (this.opts.skillDir) {
@@ -1798,14 +1932,38 @@ export class RuntimeRunner {
                                 }
                             }
                         }
-                        action = await this.commitKernelAction(runtime, this.pendingObservations, providerEvent);
+                        // P4-S1: land the attempt evidence BEFORE the kernel resolution commits — the record
+                        // describes the transport fact, which exists regardless of what the kernel decides next.
+                        const attemptTelemetry = this.opts.provider.peekTransportTelemetry?.();
                         const providerReplay = peekProviderReplay(this.opts.provider, finalText, finalToolCalls);
+                        const wireEvidence = {
+                            protocol: this.providerRoute.protocol,
+                            request_fingerprint: providerPlan.fingerprint,
+                            ...(attemptTelemetry?.responseId !== undefined ? { response_id: attemptTelemetry.responseId } : {}),
+                            ...(providerReplay !== undefined ? { replay_state: providerReplay } : {}),
+                        };
+                        await this.appendProviderAttempt(sessionId, {
+                            effectId: providerEffectId,
+                            attemptSeq: 1,
+                            route: this.providerRoute,
+                            requestFingerprint: providerPlan.fingerprint,
+                            status: "success",
+                            transportRungs: attemptTelemetry?.rungs ?? 1,
+                            startedAtMs: attemptStartedAtMs,
+                            finishedAtMs: Date.now(),
+                            ...(attemptUsage !== undefined ? { usage: attemptUsage } : {}),
+                            wireEvidence,
+                        });
+                        action = await this.commitKernelAction(runtime, this.pendingObservations, providerEvent);
                         await this.opts.sessionLog.append(sessionId, buildLlmCompletedEvent({
                             turn: runtime.turn(),
                             content: finalText,
                             tokenCount: turnOutputTokens || turnTokens || undefined,
                             toolCalls: finalToolCalls,
                             providerReplay,
+                            effectId: providerEffectId,
+                            invocationId,
+                            wireEvidence,
                         }));
                         // P0-C: emit per-turn tool-gating telemetry. `activeSkill` reflects the skill in effect
                         // GOING INTO this turn; a `skill` call here only takes effect next turn, so emit first, then
@@ -1840,7 +1998,7 @@ export class RuntimeRunner {
                         }
                     }
                     else if (action.kind === "request_approval") {
-                        const resolved = await this.resolveApprovalRequests(action.requests, runtime, sessionId);
+                        const resolved = await this.resolveApprovalRequests(action.requests, runtime, sessionId, action.effectId);
                         for (const event of resolved.events)
                             yield event;
                         action = await this.commitKernelAction(runtime, this.pendingObservations, {
@@ -2170,6 +2328,7 @@ export class RuntimeRunner {
                                 token_count: r.tokenCount,
                                 content: { blocks: toolOutputBlocksToDurable(r.contentParts?.length ? r.contentParts : [{ type: "text", text: r.output }]) },
                             })),
+                            effect_id: toolEffectId,
                         });
                         // The canonical provider resolution already activates a successfully resolved `skill` call.
                         // The host's remaining responsibility is to pin the resolved METHOD content — how to do

package/dist/runtime/session-log.d.ts

@@ -1,6 +1,7 @@
 import type { KernelPrimitive } from "./kernel-event-log.js";
-import type { ContentPart, ProviderReplay, ToolCall, ToolErrorKind } from "../types.js";
-import type { RecordedPromptMeasurement } from "../providers/request-plan.js";
+import type { ContentPart, ProviderReplay, ProviderWireEvidence, ToolCall, ToolErrorKind } from "../types.js";
+import type { RecordedPromptMeasurement, ResolvedProviderRoute } from "../providers/request-plan.js";
+import type { ProviderAttemptRecord } from "./execution-evidence.js";
 import type { MemoryRecall, MemoryScope } from "../memory/protocols.js";
 import type { KernelJournal } from "./kernel-journal.js";
 export type RollbackReason = {
@@ -30,6 +31,7 @@ export type SessionEvent = {
     agent_id?: string;
     system_prompt?: string;
     attachments?: ContentPart[];
+    route?: ResolvedProviderRoute;
 } | {
     kind: "llm_completed";
     turn: number;
@@ -37,11 +39,17 @@ export type SessionEvent = {
     token_count?: number;
     tool_calls: ToolCall[];
     provider_replay?: ProviderReplay;
+    effect_id?: string;
+    invocation_id?: string;
+    wire_evidence?: ProviderWireEvidence;
 } | {
     kind: "prompt_measured";
     turn: number;
     measurement: RecordedPromptMeasurement;
-} | {
+    effect_id?: string;
+} | ({
+    kind: "provider_attempt";
+} & ProviderAttemptRecord) | {
     kind: "tool_requested";
     turn: number;
     calls: ToolCall[];
@@ -59,6 +67,7 @@ export type SessionEvent = {
             blocks: Record<string, unknown>[];
         };
     }>;
+    effect_id?: string;
 } | {
     kind: "tool_argument_repaired";
     turn: number;
@@ -326,6 +335,14 @@ export type SessionEvent = {
     reason: string;
     coerced_from?: string;
 };
+export type SessionEventKind = SessionEvent["kind"];
+/**
+ * The registered session-event vocabulary (F9 / S3, P7-S4). This list is the single authority
+ * the cross-SDK manifest fixture pins: a kind added here without the same-commit update to
+ * `tests/fixtures/sdk-conformance/canonical/session-event-vocabulary.json` and the python/wasm
+ * vocabularies turns cross-SDK conformance red. Declared in `SessionEvent` union order.
+ */
+export declare const SESSION_EVENT_KINDS: readonly ["run_started", "llm_completed", "prompt_measured", "provider_attempt", "tool_requested", "tool_completed", "tool_argument_repaired", "tool_denied", "permission_requested", "permission_resolved", "compressed", "page_out", "semantic_archive_pending", "semantic_archive_completed", "semantic_archive_failed", "page_in", "rollbacked", "capability_changed", "context_renewed", "suspended", "resumed", "tool_gated", "signal_delivery_disposed", "budget_exceeded", "budget_usage_reported", "operation_cancelled", "milestone_advanced", "milestone_blocked", "checkpoint_taken", "entropy_sample", "entropy_alert", "agent_process_changed", "memory_written", "memory_queried", "memory_validation_failed", "memory_write_failed", "memory_query_failed", "memory_retrieval_result", "workflow_node_completed", "workflow_nodes_submitted", "workflow_batch_spawned", "workflow_completed", "kernel_observation", "run_terminal", "summary_upgraded", "group_member_joined", "group_budget_charged", "round_started", "round_paced"];
 /**
  * The business-projection log (spec §9.2): run started/terminal, stream events, observations,
  * provider/tool presentation, audit metadata.