@kontextmind/kxm 0.7.23 → 0.7.25

package/plugins/kxm/src/vnext-engine.ts

@@ -13,10 +13,12 @@ import {
 } from "./context-packet.ts";
 import { compileVnextWorkflow, type VnextCompiledPlan, type VnextCompiledStep } from "./vnext-engine-compile.ts";
 import {
+  effectiveRunDurationBudget,
   isTerminalRunStatus,
   vnextFoldPanelAttempt,
   vnextFoldPanelAttemptIds,
   vnextJoinAll,
+  type VnextRunDurationBudget,
   type VnextRunState,
 } from "./vnext-engine-fold.ts";
 import {
@@ -66,12 +68,18 @@ import {
   type VnextRuntimeContext,
 } from "./vnext-runtime.ts";
 import {
+  hashVnextDriveLog,
   newVnextAssignmentId,
   newVnextAttemptId,
   newVnextEventId,
   projectRuntimeKey,
   runtimeError,
+  verifyVnextDriveReceipt,
+  VNEXT_DRIVE_RECEIPT_SCHEMA,
   type VnextAttemptCapabilityRow,
+  type VnextDriveReceipt,
+  type VnextDriveReceiptBudget,
+  type VnextDriveReceiptHandoff,
   type VnextGateAttemptRow,
   type VnextGateEvidenceRow,
   type VnextGateObservationRow,
@@ -79,7 +87,7 @@ import {
   type VnextRunRecord,
   type VnextRunStatus,
 } from "./vnext-runtime-store.ts";
-import { vnextCanonicalJson, type JsonValue, type VnextProjectBundle } from "./vnext-config.ts";
+import { VnextConfigError, vnextCanonicalJson, type JsonValue, type VnextProjectBundle } from "./vnext-config.ts";
 import { evaluateArtifactsGate } from "./vnext-engine-artifacts.ts";
 import { createCommandObserver } from "./vnext-engine-command.ts";
 import {
@@ -383,6 +391,8 @@ async function driveAdmitted(
   }
   let latest: VnextRunDriveResult = { state: foldStoredVnextRun(context, requireRun(context, runId)) };
   while (latest.state.status === "running") {
+    const overBudget = cancelRunDurationIfExceeded(context, runId);
+    if (overBudget) return overBudget;
     const before = context.eventStore.runState(runId)?.lastSequence;
     latest = await stepLocked(context, runId, producer, token);
     if (latest.handoff) return latest;
@@ -432,6 +442,150 @@ function newDriveId(runId: string, token: string, runtimeId: string, monotonicNs
   return `drv_${createHash("sha256").update(`${runId}\0${token}\0${runtimeId}\0${monotonicNs}`, "utf8").digest("hex").slice(0, 24)}`;
 }
 
+export interface VnextDrivePollProjection {
+  driveId: string;
+  mode: "simulated" | "live";
+  openedAt: string;
+  receipt: VnextDriveReceipt | null;
+  verified: boolean;
+  divergence?: string;
+}
+
+export interface VnextDriveReceiptCloseInfo {
+  kind: "terminal" | "handoff" | "unsettled";
+  reason?: string;
+  handoff?: VnextRunHandoff;
+  error?: { class: string; component: string; retryable: boolean };
+  producerId: string;
+  producerClosed: boolean;
+}
+
+function driveErrorSummary(error: unknown): { class: string; component: string; retryable: boolean } {
+  const raw = error instanceof VnextConfigError ? error.issues[0]?.code : undefined;
+  const className = raw && /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/.test(raw) ? raw : "drive-failure";
+  return { class: className, component: "vnext-engine", retryable: false };
+}
+
+function receiptHandoff(handoff: VnextRunHandoff): VnextDriveReceiptHandoff {
+  return {
+    reason: handoff.reason,
+    detail: handoff.detail,
+    ...(handoff.field !== undefined ? { field: handoff.field } : {}),
+    ...(handoff.stepId !== undefined ? { stepId: handoff.stepId } : {}),
+  };
+}
+
+function appendDriveOpened(
+  context: VnextRuntimeContext,
+  runId: string,
+  driveId: string,
+  mode: "simulated" | "live",
+): { sequence: number; occurredAt: string } {
+  return context.eventStore.transaction(() => {
+    const run = requireRun(context, runId);
+    const now = new Date().toISOString();
+    const sequence = context.eventStore.nextSequence(runId);
+    const event: VnextRunEvent = {
+      ...vnextEventBase(context, run, now, vnextMonotonicNs()),
+      eventId: newVnextEventId(),
+      eventType: "run.drive_opened",
+      sequence,
+      payload: { driveId, mode },
+    };
+    context.eventStore.appendEvent(event);
+    const next = foldStoredVnextRun(context, run);
+    persistVnextRunState(context, runId, next, sequence);
+    return { sequence, occurredAt: now };
+  });
+}
+
+export function recordDriveReceipt(
+  context: VnextRuntimeContext,
+  session: VnextDriveSession,
+  closeInfo: VnextDriveReceiptCloseInfo,
+): void {
+  if (isVnextRuntimeContextClosed(context)) return;
+  try {
+    const run = context.eventStore.run(session.runId);
+    if (!run) return;
+    const state = foldStoredVnextRun(context, run);
+    const events = context.eventStore.events(session.runId, 0, 1_000_000);
+    if (events.length === 0) return;
+    const opened = state.drive;
+    const openedEvent = opened
+      ? events.find((event) => event.sequence === opened.openedSequence && event.eventType === "run.drive_opened")
+      : events.find((event) => event.eventType === "run.drive_opened" && event.payload.driveId === session.driveId);
+    const last = events[events.length - 1]!;
+    const openedSequence = opened?.openedSequence ?? openedEvent?.sequence;
+    if (openedSequence === undefined) return;
+    const closedAt = new Date().toISOString();
+    const receipt: VnextDriveReceipt = {
+      schema: VNEXT_DRIVE_RECEIPT_SCHEMA,
+      driveId: session.driveId,
+      runId: session.runId,
+      projectId: run.projectId,
+      homeRuntimeId: session.homeRuntimeId,
+      mode: session.mode,
+      openedAt: openedEvent?.occurredAt ?? session.openedAt,
+      openedSequence,
+      closedAt,
+      lastSequence: last.sequence,
+      logHash: hashVnextDriveLog(events.filter((event) => event.sequence >= 1 && event.sequence <= last.sequence)),
+      settlement: {
+        kind: closeInfo.kind,
+        status: state.status,
+        reason: closeInfo.reason ?? state.terminalReason ?? "",
+        ...(closeInfo.kind === "handoff" && closeInfo.handoff ? { handoff: receiptHandoff(closeInfo.handoff) } : {}),
+        ...(closeInfo.error !== undefined ? { error: closeInfo.error } : {}),
+      },
+      budget: driveReceiptBudget(context, run.runId, state, events, closedAt),
+      producer: { id: closeInfo.producerId, closed: closeInfo.producerClosed },
+    };
+    context.eventStore.insertDriveReceipt(receipt);
+  } catch {
+    // The drive result governs; a missing receipt is visible on poll.
+  }
+}
+
+export function vnextDrivePollProjection(
+  context: VnextRuntimeContext,
+  runId: string,
+  state: VnextRunState,
+): VnextDrivePollProjection | undefined {
+  if (!state.drive) return undefined;
+  const events = context.eventStore.events(runId, 0, 1_000_000);
+  const openedEvent = events.find((event) => event.sequence === state.drive!.openedSequence);
+  let receipt: VnextDriveReceipt | null = null;
+  let unreadable = false;
+  try {
+    receipt = context.eventStore.driveReceipt(state.drive.driveId) ?? null;
+  } catch {
+    unreadable = true;
+  }
+  const projection: VnextDrivePollProjection = {
+    driveId: state.drive.driveId,
+    mode: state.drive.mode,
+    openedAt: openedEvent?.occurredAt ?? "",
+    receipt: unreadable ? null : receipt,
+    verified: false,
+  };
+  if (unreadable) {
+    projection.divergence = "receipt unreadable";
+    return projection;
+  }
+  if (!receipt) {
+    projection.divergence = "no receipt";
+    return projection;
+  }
+  const checked = verifyVnextDriveReceipt(receipt, events, state.status, {
+    runId,
+    driveId: state.drive.driveId,
+  });
+  projection.verified = checked.verified;
+  if (checked.divergence !== undefined) projection.divergence = checked.divergence;
+  return projection;
+}
+
 function inflightAttemptId(state: VnextRunState): string | undefined {
   const leftover = unreconciledPanelAttemptId(state);
   if (leftover) return leftover;
@@ -595,25 +749,50 @@ export class VnextRunScheduler {
               throw error;
             }
             const driveId = newDriveId(runId, token, this.context.homeRuntimeId, vnextMonotonicNs());
+            const openedMeta = appendDriveOpened(this.context, runId, driveId, options.mode);
+            const startedState = foldStoredVnextRun(this.context, requireRun(this.context, runId));
+            const deadlineAt = driveDeadlineAt(this.context, runId, startedState);
             const session: VnextDriveSession = {
               driveId,
               runId,
               token,
               homeRuntimeId: this.context.homeRuntimeId,
               mode: options.mode,
-              openedAt: new Date().toISOString(),
+              openedAt: openedMeta.occurredAt,
+              producerId: producer.id,
               controller: new AbortController(),
               settled,
+              ...(deadlineAt !== undefined ? { deadlineAt } : {}),
             };
             attachVnextDriveSession(this.context.eventStore.path, runId, token, session);
             opened = true;
             resolveOpen({ driveId, settled });
             try {
               const result = await driveAdmitted(this.context, runId, producer, token, driveOptions);
+              const kind = result.handoff ? "handoff" : isTerminalRunStatus(result.state.status) ? "terminal" : "unsettled";
+              recordDriveReceipt(this.context, session, {
+                kind,
+                ...(result.state.terminalReason !== undefined ? { reason: result.state.terminalReason } : result.handoff ? { reason: result.handoff.reason } : {}),
+                ...(result.handoff ? { handoff: result.handoff } : {}),
+                producerId: producer.id,
+                producerClosed: false,
+              });
               pending.resolve(result);
               return result;
             } catch (error) {
               recordBareDriveFailure(this.context, runId);
+              let foldedStatus: string | undefined;
+              try {
+                foldedStatus = foldStoredVnextRun(this.context, requireRun(this.context, runId)).status;
+              } catch {
+                foldedStatus = undefined;
+              }
+              recordDriveReceipt(this.context, session, {
+                kind: foldedStatus !== undefined && isTerminalRunStatus(foldedStatus as VnextRunStatus) ? "terminal" : "unsettled",
+                error: driveErrorSummary(error),
+                producerId: producer.id,
+                producerClosed: false,
+              });
               pending.reject(error);
               throw error;
             }
@@ -730,11 +909,13 @@ async function stepLocked(context: VnextRuntimeContext, runId: string, producer:
       throw runtimeError("run_events_illegal", prepared.run.runId, "prepared gate is not artifacts-exist");
     }
     registerVnextAttemptController(context.eventStore.path, runId, { attemptId: prepared.attemptId, controller: prepared.controller });
+    const clearBudget = armRunDurationBudgetTimer(context, runId);
     try {
       const observation = evaluateArtifactsGate(context, definition);
       vnextGateDispatchSeams.afterEvaluate?.(prepared);
       return context.eventStore.transaction(() => settlePreparedGate(context, prepared, observation));
     } finally {
+      clearBudget();
       unregisterVnextAttemptController(context.eventStore.path, runId, prepared.attemptId);
     }
   }
@@ -775,6 +956,7 @@ async function runPreparedCommandGate(
   });
   armVnextGateHold(storePath, prepared.run.runId, token, prepared.attemptId, () => observer.requestStop("cancel"));
   registerVnextAttemptController(storePath, prepared.run.runId, { attemptId: prepared.attemptId, controller: prepared.controller });
+  const clearBudget = armRunDurationBudgetTimer(context, prepared.run.runId);
   const unhookClose = registerVnextRuntimeCloseHook(context, () => {
     try {
       markVnextGateHoldUnsettled(storePath, prepared.run.runId, token, prepared.attemptId);
@@ -822,6 +1004,7 @@ async function runPreparedCommandGate(
     return commitCommandUncertainty(context, prepared, token, outcome.reason, outcome.observation);
   } finally {
     unhookClose();
+    clearBudget();
     unregisterVnextAttemptController(storePath, prepared.run.runId, prepared.attemptId);
   }
 }
@@ -1628,8 +1811,10 @@ async function drivePanel(
   let stopBirths = false;
   let settlementFailed = false;
 
+  const budgetClears = new Map<string, () => void>();
   const register = (member: PreparedDispatch): void => {
     registerVnextAttemptController(context.eventStore.path, runId, { attemptId: member.attemptId, controller: member.controller });
+    budgetClears.set(member.attemptId, armRunDurationBudgetTimer(context, runId));
     owned.set(member.attemptId, member);
   };
 
@@ -1836,6 +2021,7 @@ async function drivePanel(
     throw error;
   } finally {
     for (const attemptId of owned.keys()) {
+      budgetClears.get(attemptId)?.();
       unregisterVnextAttemptController(context.eventStore.path, runId, attemptId);
     }
   }
@@ -2024,7 +2210,7 @@ function joinPanel(context: VnextRuntimeContext, panel: PreparedPanel): VnextRun
 
   const cancelRun = (): VnextRunDriveResult => {
     push("step.status_changed", { stepId: panel.stepId, status: "cancelled", previousStatus: "running" });
-    push("run.status_changed", { status: "cancelled", reason: "operator_cancel" });
+    push("run.status_changed", { status: "cancelled", reason: cancelReasonFromLog(context, run.runId) });
     for (const event of events) context.eventStore.appendEvent(event);
     const next = foldStoredVnextRun(context, run);
     persistVnextRunState(context, run.runId, next, events[events.length - 1]!.sequence);
@@ -2146,16 +2332,146 @@ function transitionBudgetFailure(plan: VnextCompiledPlan, state: VnextRunState,
   return undefined;
 }
 
-function unsupportedLimit(envelope: VnextRunPlanEnvelope): VnextRunHandoff | undefined {
-  if (envelope.plan.limits.maxRunDurationMs !== undefined) {
-    return { reason: "limit_unsupported", field: "limits.maxRunDurationMs", detail: "duration budget enforcement is not available in this slice" };
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+function elapsedMsBetween(fromIso: string, toIso: string): number {
+  const from = Date.parse(fromIso);
+  const to = Date.parse(toIso);
+  if (!Number.isFinite(from) || !Number.isFinite(to)) return 0;
+  return Math.max(0, Math.trunc(to - from));
+}
+
+function declaredRunDurationBudget(context: VnextRuntimeContext, runId: string): VnextRunDurationBudget | undefined {
+  const run = context.eventStore.run(runId);
+  if (!run) return undefined;
+  try {
+    const envelope = loadVnextRunPlanEnvelope(context.eventStore, run);
+    return effectiveRunDurationBudget(envelope.plan.limits, envelope.projectLimits);
+  } catch {
+    return undefined;
+  }
+}
+
+function runDurationOverrunPayload(
+  context: VnextRuntimeContext,
+  runId: string,
+  nowIso = new Date().toISOString(),
+): { budgetMs: number; elapsedMs: number; source: VnextRunDurationBudget["source"] } | undefined {
+  const declared = declaredRunDurationBudget(context, runId);
+  if (!declared) return undefined;
+  const run = context.eventStore.run(runId);
+  if (!run) return undefined;
+  const state = foldStoredVnextRun(context, run);
+  if (!state.runningSince) return undefined;
+  if (isTerminalRunStatus(state.status) || state.status === "cancelling") return undefined;
+  const elapsedMs = elapsedMsBetween(state.runningSince, nowIso);
+  if (elapsedMs < declared.budgetMs) return undefined;
+  return { budgetMs: declared.budgetMs, elapsedMs, source: declared.source };
+}
+
+function cancelRunDurationIfExceeded(context: VnextRuntimeContext, runId: string): VnextRunDriveResult | undefined {
+  if (isVnextRuntimeContextClosed(context)) return undefined;
+  const payload = runDurationOverrunPayload(context, runId);
+  if (!payload) return undefined;
+  cancelVnextRun(context, runId, { reason: "budget_run_duration", budget: payload });
+  return { state: foldStoredVnextRun(context, requireRun(context, runId)) };
+}
+
+function driveDeadlineAt(context: VnextRuntimeContext, runId: string, state: VnextRunState): string | undefined {
+  const declared = declaredRunDurationBudget(context, runId);
+  if (!declared || !state.runningSince) return undefined;
+  const start = Date.parse(state.runningSince);
+  if (!Number.isFinite(start)) return undefined;
+  return new Date(start + declared.budgetMs).toISOString();
+}
+
+function driveReceiptBudget(
+  context: VnextRuntimeContext,
+  runId: string,
+  state: VnextRunState,
+  events: readonly VnextRunEvent[],
+  closedAt: string,
+): VnextDriveReceiptBudget | null {
+  const declared = declaredRunDurationBudget(context, runId);
+  if (!declared) return null;
+  const elapsedMs = state.runningSince ? elapsedMsBetween(state.runningSince, closedAt) : 0;
+  const overrun = events.some((event) => (
+    event.eventType === "run.cancel_requested" && event.payload.reason === "budget_run_duration"
+  ));
+  return {
+    budgetMs: declared.budgetMs,
+    source: declared.source,
+    elapsedMs,
+    overrun,
+  };
+}
+
+function cancelReasonFromLog(context: VnextRuntimeContext, runId: string): string {
+  const events = context.eventStore.events(runId, 0, 1_000_000);
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index]!;
+    if (event.eventType === "run.cancel_requested" && typeof event.payload.reason === "string") {
+      return event.payload.reason;
+    }
   }
+  return "operator_cancel";
+}
+
+function armRunDurationBudgetTimer(context: VnextRuntimeContext, runId: string): () => void {
+  const declared = declaredRunDurationBudget(context, runId);
+  if (!declared) return () => undefined;
+  const run = context.eventStore.run(runId);
+  if (!run) return () => undefined;
+  const state = foldStoredVnextRun(context, run);
+  if (!state.runningSince) return () => undefined;
+  const startMs = Date.parse(state.runningSince);
+  if (!Number.isFinite(startMs)) return () => undefined;
+  const deadlineMs = startMs + declared.budgetMs;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let cleared = false;
+  const fire = (): void => {
+    timer = undefined;
+    if (cleared || isVnextRuntimeContextClosed(context)) return;
+    const nowIso = new Date().toISOString();
+    const elapsedMs = elapsedMsBetween(state.runningSince!, nowIso);
+    if (elapsedMs < declared.budgetMs) {
+      arm(declared.budgetMs - elapsedMs);
+      return;
+    }
+    try {
+      cancelVnextRun(context, runId, {
+        reason: "budget_run_duration",
+        budget: { budgetMs: declared.budgetMs, elapsedMs, source: declared.source },
+      });
+    } catch {
+      // Already cancelling, terminal, or the store closed under us.
+    }
+  };
+  const arm = (remaining: number): void => {
+    if (cleared) return;
+    const delay = Math.min(Math.max(0, remaining), MAX_TIMER_DELAY_MS);
+    timer = setTimeout(fire, delay);
+    timer.unref();
+  };
+  const unhook = registerVnextRuntimeCloseHook(context, () => {
+    cleared = true;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+  });
+  arm(deadlineMs - Date.now());
+  return () => {
+    if (cleared) return;
+    cleared = true;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+    unhook();
+  };
+}
+
+function unsupportedLimit(envelope: VnextRunPlanEnvelope): VnextRunHandoff | undefined {
   if (envelope.plan.limits.maxAgentTimeMs !== undefined) {
     return { reason: "limit_unsupported", field: "limits.maxAgentTimeMs", detail: "agent-time budget enforcement is not available in this slice" };
   }
-  if (envelope.projectLimits.maxRunDurationMs !== undefined) {
-    return { reason: "limit_unsupported", field: "project.limits.maxRunDurationMs", detail: "duration budget enforcement is not available in this slice" };
-  }
   if (envelope.projectLimits.maxAgentTimeMs !== undefined) {
     return { reason: "limit_unsupported", field: "project.limits.maxAgentTimeMs", detail: "agent-time budget enforcement is not available in this slice" };
   }

package/plugins/kxm/src/vnext-runtime-owner.ts

@@ -26,8 +26,10 @@ export interface VnextDriveSession {
   homeRuntimeId: string;
   mode: "simulated" | "live";
   openedAt: string;
+  producerId: string;
   controller: AbortController;
   settled: Promise<unknown>;
+  deadlineAt?: string;
 }
 
 interface AdmissionRecord {

package/plugins/kxm/src/vnext-runtime-store.ts

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { DatabaseSync } from "./sqlite.ts";
-import { VnextConfigError, validateRunEvent, vnextCanonicalJson, type JsonValue, type VnextConfigIssue, type VnextConfigOptions } from "./vnext-config.ts";
+import { VnextConfigError, validateDriveReceipt, validateRunEvent, vnextCanonicalJson, type JsonValue, type VnextConfigIssue, type VnextConfigOptions } from "./vnext-config.ts";
 import { vnextUserStateRoot } from "./vnext-bindings.ts";
 
 /* ------------------------------------------------------------------ *
@@ -364,6 +364,80 @@ export interface VnextRunStateRow {
   state: string;
 }
 
+export interface VnextDriveReceiptHandoff {
+  reason: string;
+  field?: string;
+  stepId?: string;
+  detail: string;
+}
+
+export interface VnextDriveReceiptSettlement {
+  kind: "terminal" | "handoff" | "unsettled";
+  status: string;
+  reason: string;
+  handoff?: VnextDriveReceiptHandoff;
+  error?: { class: string; component: string; retryable: boolean };
+}
+
+export interface VnextDriveReceipt {
+  schema: typeof VNEXT_DRIVE_RECEIPT_SCHEMA;
+  driveId: string;
+  runId: string;
+  projectId: string;
+  homeRuntimeId: string;
+  mode: "simulated" | "live";
+  openedAt: string;
+  openedSequence: number;
+  closedAt: string;
+  lastSequence: number;
+  logHash: string;
+  settlement: VnextDriveReceiptSettlement;
+  budget: VnextDriveReceiptBudget | null;
+  producer: { id: string; closed: boolean };
+}
+
+export interface VnextDriveReceiptBudget {
+  budgetMs: number;
+  source: "workflow" | "project" | "both";
+  elapsedMs: number;
+  overrun: boolean;
+}
+
+/** sha256 over `eventId:sequence` for events 1..lastSequence, in sequence order. */
+export function hashVnextDriveLog(events: readonly { eventId: string; sequence: number }[]): string {
+  const body = events.map((event) => `${event.eventId}:${event.sequence}`).join("\n");
+  return `sha256:${createHash("sha256").update(body, "utf8").digest("hex")}`;
+}
+
+export function verifyVnextDriveReceipt(
+  receipt: VnextDriveReceipt,
+  events: readonly VnextRunEvent[],
+  foldedStatus: string,
+  binding: { runId: string; driveId: string },
+): { verified: boolean; divergence?: string } {
+  const reasons: string[] = [];
+  if (receipt.runId !== binding.runId) {
+    reasons.push(`runId ${receipt.runId} != binding ${binding.runId}`);
+  }
+  if (receipt.driveId !== binding.driveId) {
+    reasons.push(`driveId ${receipt.driveId} != binding ${binding.driveId}`);
+  }
+  const last = events[events.length - 1];
+  const currentLast = last?.sequence ?? 0;
+  if (receipt.lastSequence !== currentLast) {
+    reasons.push(`lastSequence ${receipt.lastSequence} != log ${currentLast}`);
+  }
+  const prefix = events.filter((event) => event.sequence >= 1 && event.sequence <= receipt.lastSequence);
+  if (hashVnextDriveLog(prefix) !== receipt.logHash) {
+    reasons.push("logHash mismatch");
+  }
+  if (receipt.settlement.status !== foldedStatus) {
+    reasons.push(`settlement.status ${receipt.settlement.status} != folded ${foldedStatus}`);
+  }
+  if (reasons.length === 0) return { verified: true };
+  return { verified: false, divergence: reasons.join("; ") };
+}
+
 export interface VnextAttemptCapabilityRow {
   attemptId: string;
   runId: string;
@@ -472,7 +546,9 @@ export interface VnextCommandRecord {
   recordedAt: string;
 }
 
-export const VNEXT_EVENT_STORE_SCHEMA_VERSION = 3;
+export const VNEXT_EVENT_STORE_SCHEMA_VERSION = 4;
+export const VNEXT_DRIVE_RECEIPT_SCHEMA = "kxm.drive-receipt.v1";
+export const DRIVE_RECEIPT_MAX_BYTES = 8 * 1024;
 
 const EVENT_STORE_TABLES = {
   runs: ["run_id", "project_id", "home_runtime_id", "workflow_id", "prompt_sha256", "status", "config_revision", "memory_revision", "executor_policy_revision", "tool_policy_revision", "created_at", "updated_at"],
@@ -497,6 +573,7 @@ const EVENT_STORE_TABLES = {
     "evidence_id", "attempt_id", "observation_id", "run_id", "project_id", "home_runtime_id", "step_id", "step_attempt",
     "assignment_id", "effect_id", "evidence_key", "kind", "expect", "outcome", "settled_event_id", "content_hash",
   ],
+  drive_receipts: ["drive_id", "run_id", "project_id", "opened_sequence", "last_sequence", "closed_at", "schema", "receipt"],
 } as const;
 
 const EVENT_STORE_SCHEMA = `
@@ -639,8 +716,43 @@ CREATE TABLE gate_evidence (
 ) STRICT;
 CREATE UNIQUE INDEX gate_evidence_key ON gate_evidence(run_id, step_id, step_attempt, evidence_key) WHERE evidence_key IS NOT NULL;
 CREATE INDEX gate_evidence_run ON gate_evidence(run_id);
+CREATE TABLE drive_receipts (
+  drive_id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL,
+  project_id TEXT NOT NULL,
+  opened_sequence INTEGER NOT NULL,
+  last_sequence INTEGER NOT NULL,
+  closed_at TEXT NOT NULL,
+  schema TEXT NOT NULL,
+  receipt TEXT NOT NULL
+) STRICT;
+CREATE INDEX drive_receipts_run ON drive_receipts(run_id);
 `;
 
+const DRIVE_RECEIPTS_DDL = `
+CREATE TABLE IF NOT EXISTS drive_receipts (
+  drive_id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL,
+  project_id TEXT NOT NULL,
+  opened_sequence INTEGER NOT NULL,
+  last_sequence INTEGER NOT NULL,
+  closed_at TEXT NOT NULL,
+  schema TEXT NOT NULL,
+  receipt TEXT NOT NULL
+) STRICT;
+CREATE INDEX IF NOT EXISTS drive_receipts_run ON drive_receipts(run_id);
+`;
+
+const EVENT_STORE_MIGRATIONS = [
+  {
+    fromVersion: 3,
+    toVersion: 4,
+    migrate(database: DatabaseSync): void {
+      database.exec(DRIVE_RECEIPTS_DDL);
+    },
+  },
+];
+
 export class VnextRunEventStore {
   readonly path: string;
   private readonly database: DatabaseSync;
@@ -651,6 +763,7 @@ export class VnextRunEventStore {
       schema: EVENT_STORE_SCHEMA,
       version: VNEXT_EVENT_STORE_SCHEMA_VERSION,
       tables: EVENT_STORE_TABLES,
+      migrations: EVENT_STORE_MIGRATIONS,
     });
   }
 
@@ -871,6 +984,43 @@ export class VnextRunEventStore {
     `).run(row.runId, row.lastSequence, row.state);
   }
 
+  insertDriveReceipt(receipt: VnextDriveReceipt): { inserted: boolean } {
+    validateDriveReceipt(receipt, "drive-receipt");
+    const canonical = vnextCanonicalJson(receipt as unknown as JsonValue);
+    if (Buffer.byteLength(canonical, "utf8") > DRIVE_RECEIPT_MAX_BYTES) {
+      throw runtimeError("drive_receipt_invalid", receipt.driveId, `drive receipt exceeds ${DRIVE_RECEIPT_MAX_BYTES} bytes`);
+    }
+    const result = this.database.prepare(`
+      INSERT INTO drive_receipts (drive_id, run_id, project_id, opened_sequence, last_sequence, closed_at, schema, receipt)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(drive_id) DO NOTHING
+    `).run(
+      receipt.driveId,
+      receipt.runId,
+      receipt.projectId,
+      receipt.openedSequence,
+      receipt.lastSequence,
+      receipt.closedAt,
+      receipt.schema,
+      canonical,
+    );
+    return { inserted: Number(result.changes) === 1 };
+  }
+
+  driveReceipt(driveId: string): VnextDriveReceipt | undefined {
+    const row = this.database.prepare("SELECT receipt FROM drive_receipts WHERE drive_id = ?").get(driveId) as
+      | { receipt: string }
+      | undefined;
+    return row ? parseDriveReceipt(row.receipt) : undefined;
+  }
+
+  driveReceiptsForRun(runId: string, limit = 20): VnextDriveReceipt[] {
+    const rows = this.database.prepare(`
+      SELECT receipt FROM drive_receipts WHERE run_id = ? ORDER BY closed_at DESC, drive_id DESC LIMIT ?
+    `).all(runId, limit) as Array<{ receipt: string }>;
+    return rows.map((row) => parseDriveReceipt(row.receipt));
+  }
+
   insertCapability(row: VnextAttemptCapabilityRow): void {
     this.database.prepare(`
       INSERT INTO attempt_capabilities (attempt_id, run_id, assignment_id, step_id, step_attempt, producer_id, capability_hash, state)
@@ -1075,6 +1225,12 @@ export class VnextRunEventStore {
   }
 }
 
+function parseDriveReceipt(raw: string): VnextDriveReceipt {
+  const parsed = JSON.parse(raw) as unknown;
+  validateDriveReceipt(parsed, "drive-receipt");
+  return parsed as VnextDriveReceipt;
+}
+
 function runFromRow(row: {
   run_id: string;
   project_id: string;