@kontextmind/kxm 0.7.23 → 0.7.24

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

@@ -107,6 +107,12 @@ export interface VnextRunCurrentStep {
   readonly evidenceRefs?: readonly { id: string; kind: string; hash: string; status: string }[] | undefined;
 }
 
+export interface VnextRunDriveBinding {
+  readonly driveId: string;
+  readonly mode: "simulated" | "live";
+  readonly openedSequence: number;
+}
+
 export interface VnextRunState {
   readonly schema: typeof VNEXT_RUN_STATE_SCHEMA;
   readonly runId: string;
@@ -120,6 +126,7 @@ export interface VnextRunState {
   readonly cancelRequested: boolean;
   readonly terminalReason?: string | undefined;
   readonly failureReason?: string | undefined;
+  readonly drive?: VnextRunDriveBinding | undefined;
 }
 
 interface MutableAttempt {
@@ -171,6 +178,7 @@ interface MutableState {
   awaitingTransition: boolean;
   cancelCommandId?: string | undefined;
   lastTerminalTransition?: VnextTerminalStatus | undefined;
+  drive?: VnextRunDriveBinding | undefined;
 }
 
 function emptyPanel(): MutablePanel {
@@ -462,6 +470,9 @@ export function foldVnextRunState(
       case "run.cancel_requested":
         foldCancelRequested(state, event);
         break;
+      case "run.drive_opened":
+        foldDriveOpened(state, event);
+        break;
       case "step.entered":
         foldStepEntered(state, plan!, event);
         break;
@@ -694,6 +705,18 @@ function isProvenFailure(state: MutableState, plan: VnextCompiledPlan | undefine
   return Boolean(step && used >= step.maxAttempts);
 }
 
+function foldDriveOpened(state: MutableState, event: VnextRunEvent): void {
+  if (state.status !== "running" && state.status !== "blocked_uncertain") {
+    throw runtimeError("run_events_illegal", state.runId, "run.drive_opened is only legal while running or blocked_uncertain");
+  }
+  const driveId = stringPayload(event, "driveId");
+  const mode = stringPayload(event, "mode");
+  if (mode !== "simulated" && mode !== "live") {
+    throw runtimeError("run_events_illegal", state.runId, "run.drive_opened mode must be simulated or live");
+  }
+  state.drive = { driveId, mode, openedSequence: event.sequence };
+}
+
 function foldCancelRequested(state: MutableState, event: VnextRunEvent): void {
   if (state.cancelRequested || TERMINAL_RUN.has(state.status)) {
     throw runtimeError("run_events_illegal", state.runId, "duplicate run.cancel_requested is not legal");
@@ -1379,6 +1402,7 @@ function freezeState(state: MutableState): VnextRunState {
     cancelRequested: state.cancelRequested,
     ...(state.terminalReason !== undefined ? { terminalReason: state.terminalReason } : {}),
     ...(state.terminalReason !== undefined && state.status === "failed" ? { failureReason: state.terminalReason } : {}),
+    ...(state.drive !== undefined ? { drive: Object.freeze({ ...state.drive }) } : {}),
   };
   return Object.freeze(frozen);
 }

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

@@ -66,12 +66,17 @@ import {
   type VnextRuntimeContext,
 } from "./vnext-runtime.ts";
 import {
+  hashVnextDriveLog,
   newVnextAssignmentId,
   newVnextAttemptId,
   newVnextEventId,
   projectRuntimeKey,
   runtimeError,
+  verifyVnextDriveReceipt,
+  VNEXT_DRIVE_RECEIPT_SCHEMA,
   type VnextAttemptCapabilityRow,
+  type VnextDriveReceipt,
+  type VnextDriveReceiptHandoff,
   type VnextGateAttemptRow,
   type VnextGateEvidenceRow,
   type VnextGateObservationRow,
@@ -79,7 +84,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 {
@@ -432,6 +437,149 @@ 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 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: new Date().toISOString(),
+      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: null,
+      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,13 +743,15 @@ export class VnextRunScheduler {
               throw error;
             }
             const driveId = newDriveId(runId, token, this.context.homeRuntimeId, vnextMonotonicNs());
+            const openedMeta = appendDriveOpened(this.context, runId, driveId, options.mode);
             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,
             };
@@ -610,10 +760,30 @@ export class VnextRunScheduler {
             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;
             }

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

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

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,73 @@ 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: null;
+  producer: { id: string; closed: 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 +539,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 +566,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 +709,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 +756,7 @@ export class VnextRunEventStore {
       schema: EVENT_STORE_SCHEMA,
       version: VNEXT_EVENT_STORE_SCHEMA_VERSION,
       tables: EVENT_STORE_TABLES,
+      migrations: EVENT_STORE_MIGRATIONS,
     });
   }
 
@@ -871,6 +977,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 +1218,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;

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

@@ -23,7 +23,7 @@ import {
 } from "./vnext-runtime.ts";
 import { createVnextOneShotProducer } from "./vnext-oneshot-producer.ts";
 import { isProducerAdmitted } from "./producers.ts";
-import { VnextRunScheduler, createVnextSimulatedProducer, recoverVnextRun } from "./vnext-engine.ts";
+import { VnextRunScheduler, createVnextSimulatedProducer, recordDriveReceipt, recoverVnextRun, vnextDrivePollProjection } from "./vnext-engine.ts";
 import { vnextOpenDriveSessions } from "./vnext-runtime-owner.ts";
 
 /* ------------------------------------------------------------------ *
@@ -318,6 +318,16 @@ async function waitForDriveSessions(settled: Promise<unknown>[], graceMs: number
   }
 }
 
+async function driveSessionStillPending(settled: Promise<unknown>): Promise<boolean> {
+  let pending = true;
+  void settled.then(
+    () => { pending = false; },
+    () => { pending = false; },
+  );
+  await Promise.resolve();
+  return pending;
+}
+
 export interface VnextRuntimeSupervisor {
   server: Server;
   port: number;
@@ -446,7 +456,9 @@ async function startVnextRuntimeSupervisorInner(
           const bundle = loadVnextProject(projectRoot, {});
           if (request.method === "GET" && !sub) {
             const projected = rebuildVnextRunProjection(context, runId);
-            sendJson(response, 200, { ok: true, run: projected });
+            const folded = foldStoredVnextRun(context, projected);
+            const drive = vnextDrivePollProjection(context, runId, folded);
+            sendJson(response, 200, { ok: true, run: projected, ...(drive !== undefined ? { drive } : {}) });
             return;
           }
           if (request.method === "POST" && sub === "drive") {
@@ -684,6 +696,15 @@ async function startVnextRuntimeSupervisorInner(
       }
     }
     await waitForDriveSessions(openSessions.map(({ session }) => session.settled), runtimeStopGraceMs());
+    for (const { context, session } of openSessions) {
+      if (!(await driveSessionStillPending(session.settled))) continue;
+      recordDriveReceipt(context, session, {
+        kind: "unsettled",
+        reason: "runtime_shutdown_grace_expired",
+        producerId: session.producerId,
+        producerClosed: false,
+      });
+    }
     for (const context of contexts.values()) closeVnextRuntimeContext(context);
     contexts.clear();
     const closed = new Promise<void>((resolveStop) => server.close(() => resolveStop()));

package/schemas/vnext/common.schema.json

@@ -164,6 +164,7 @@
         "run.created",
         "run.status_changed",
         "run.cancel_requested",
+        "run.drive_opened",
         "step.entered",
         "step.status_changed",
         "step.outcome_recorded",

package/schemas/vnext/drive-receipt.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kxm.dev/vnext/drive-receipt.schema.json",
+  "title": "KXM vNext drive session receipt",
+  "type": "object",
+  "required": [
+    "schema",
+    "driveId",
+    "runId",
+    "projectId",
+    "homeRuntimeId",
+    "mode",
+    "openedAt",
+    "openedSequence",
+    "closedAt",
+    "lastSequence",
+    "logHash",
+    "settlement",
+    "budget",
+    "producer"
+  ],
+  "properties": {
+    "schema": { "const": "kxm.drive-receipt.v1" },
+    "driveId": { "$ref": "common.schema.json#/$defs/opaqueId" },
+    "runId": { "$ref": "common.schema.json#/$defs/opaqueId" },
+    "projectId": { "$ref": "common.schema.json#/$defs/opaqueId" },
+    "homeRuntimeId": { "$ref": "common.schema.json#/$defs/opaqueId" },
+    "mode": { "enum": ["simulated", "live"] },
+    "openedAt": { "$ref": "common.schema.json#/$defs/timestamp" },
+    "openedSequence": { "type": "integer", "minimum": 1 },
+    "closedAt": { "$ref": "common.schema.json#/$defs/timestamp" },
+    "lastSequence": { "type": "integer", "minimum": 1 },
+    "logHash": { "$ref": "common.schema.json#/$defs/sha256" },
+    "settlement": { "$ref": "#/$defs/settlement" },
+    "budget": { "type": "null" },
+    "producer": {
+      "type": "object",
+      "required": ["id", "closed"],
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/identifier" },
+        "closed": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "settlement": {
+      "type": "object",
+      "required": ["kind", "status", "reason"],
+      "properties": {
+        "kind": { "enum": ["terminal", "handoff", "unsettled"] },
+        "status": { "$ref": "common.schema.json#/$defs/lifecycleStatus" },
+        "reason": { "type": "string", "maxLength": 4000 },
+        "handoff": { "$ref": "#/$defs/handoff" },
+        "error": { "$ref": "common.schema.json#/$defs/errorSummary" }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": { "properties": { "kind": { "const": "handoff" } }, "required": ["kind"] },
+          "then": { "required": ["handoff"] },
+          "else": { "not": { "required": ["handoff"] } }
+        }
+      ]
+    },
+    "handoff": {
+      "type": "object",
+      "required": ["reason", "detail"],
+      "properties": {
+        "reason": { "type": "string", "minLength": 1, "maxLength": 80 },
+        "field": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "stepId": { "$ref": "common.schema.json#/$defs/identifier" },
+        "detail": { "type": "string", "minLength": 1, "maxLength": 4000 }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/vnext/run-event.schema.json

@@ -278,6 +278,14 @@
           "payload": { "type": "object", "required": ["routing"] }
         }
       }
+    },
+    {
+      "if": { "properties": { "eventType": { "const": "run.drive_opened" } }, "required": ["eventType"] },
+      "then": {
+        "properties": {
+          "payload": { "type": "object", "required": ["driveId", "mode"] }
+        }
+      }
     }
   ],
   "additionalProperties": false,
@@ -394,6 +402,8 @@
           "maxItems": 64
         },
         "lease": { "$ref": "common.schema.json#/$defs/lease" },
+        "driveId": { "$ref": "common.schema.json#/$defs/opaqueId" },
+        "mode": { "enum": ["simulated", "live"] },
         "candidateId": { "$ref": "common.schema.json#/$defs/opaqueId" },
         "counts": {
           "type": "object",