@opengeni/db 0.14.3 → 0.16.2

package/src/schema.ts

@@ -73,6 +73,17 @@ export const workspaces = pgTable(
     // .references(), because `rigs` is declared later in this file (same
     // forward-reference pattern as sessions.activeSandboxId). Consumed in M3.
     defaultRigId: uuid("default_rig_id"),
+    // Workspace-wide viewer admission intent set by the warm-meter reaper when
+    // managed credits or the monthly warm allowance are exhausted. It is
+    // deliberately independent of a lease so a dashboard cannot re-arm a
+    // draining box or spawn a cold successor before a fresh limit evaluation
+    // clears the gate.
+    sandboxViewerForceDrainReason: text("sandbox_viewer_force_drain_reason", {
+      enum: ["balance", "warm_cap"],
+    }),
+    sandboxViewerForceDrainRequestedAt: timestamp("sandbox_viewer_force_drain_requested_at", {
+      withTimezone: true,
+    }),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
   },
@@ -82,6 +93,19 @@ export const workspaces = pgTable(
       .on(table.accountId, table.slug)
       .where(sql`${table.slug} is not null`),
     external: uniqueIndex("workspaces_external_idx").on(table.externalSource, table.externalId),
+    sandboxViewerForceDrain: index("workspaces_sandbox_viewer_force_drain_idx")
+      .on(table.id)
+      .where(sql`${table.sandboxViewerForceDrainReason} is not null`),
+    sandboxViewerForceDrainValid: check(
+      "workspaces_sandbox_viewer_force_drain_check",
+      sql`(
+          ${table.sandboxViewerForceDrainReason} is null
+          and ${table.sandboxViewerForceDrainRequestedAt} is null
+        ) or (
+          ${table.sandboxViewerForceDrainReason} in ('balance', 'warm_cap')
+          and ${table.sandboxViewerForceDrainRequestedAt} is not null
+        )`,
+    ),
   }),
 );
 
@@ -599,6 +623,90 @@ export const slackBotPostOperations = pgTable(
   }),
 );
 
+// Durable provider-operation identity for OpenGeni Slack bot deletions. Slack
+// has no client-supplied idempotency key for chat.delete, so an expired
+// provider_started claim becomes outcome_unknown and must be reconciled before
+// another mutation is admitted.
+export const slackBotDeleteOperations = pgTable(
+  "slack_bot_delete_operations",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id")
+      .notNull()
+      .references(() => managedAccounts.id, { onDelete: "cascade" }),
+    workspaceId: uuid("workspace_id")
+      .notNull()
+      .references(() => workspaces.id, { onDelete: "cascade" }),
+    connectionId: uuid("connection_id")
+      .notNull()
+      .references(() => connections.id, { onDelete: "cascade" }),
+    operationId: uuid("operation_id").notNull(),
+    principalType: text("principal_type").$type<"subject" | "service">().notNull(),
+    principalId: text("principal_id").notNull(),
+    toolName: text("tool_name").notNull(),
+    channelId: text("channel_id").notNull(),
+    messageTimestamp: text("message_timestamp").notNull(),
+    requestDigest: text("request_digest").notNull(),
+    status: text("status")
+      .$type<"pending" | "provider_started" | "outcome_unknown" | "completed">()
+      .notNull(),
+    claimHolderId: uuid("claim_holder_id"),
+    claimExpiresAt: timestamp("claim_expires_at", { withTimezone: true }),
+    attemptCount: integer("attempt_count").notNull().default(0),
+    lastFailureCode: text("last_failure_code"),
+    slackChannelId: text("slack_channel_id"),
+    slackMessageTimestamp: text("slack_message_timestamp"),
+    completedAt: timestamp("completed_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    workspaceOperation: uniqueIndex("slack_bot_delete_operations_workspace_operation_uq").on(
+      table.workspaceId,
+      table.operationId,
+    ),
+    workspaceStatus: index("slack_bot_delete_operations_workspace_status_idx").on(
+      table.workspaceId,
+      table.status,
+      table.updatedAt,
+    ),
+    principalValid: check(
+      "slack_bot_delete_operations_principal_check",
+      sql`${table.principalType} in ('subject', 'service')
+        and length(${table.principalId}) between 1 and 512`,
+    ),
+    identityValid: check(
+      "slack_bot_delete_operations_identity_check",
+      sql`${table.toolName} = 'slack_bot_delete_message'
+        and length(${table.channelId}) between 1 and 64
+        and length(${table.messageTimestamp}) between 1 and 64
+        and ${table.requestDigest} ~ '^[0-9a-f]{64}$'
+        and ${table.attemptCount} > 0
+        and ((${table.claimHolderId} is null) = (${table.claimExpiresAt} is null))`,
+    ),
+    statusValid: check(
+      "slack_bot_delete_operations_status_check",
+      sql`${table.status} in ('pending', 'provider_started', 'outcome_unknown', 'completed')`,
+    ),
+    completionValid: check(
+      "slack_bot_delete_operations_completion_check",
+      sql`(
+          ${table.status} <> 'completed'
+          and ${table.slackChannelId} is null
+          and ${table.slackMessageTimestamp} is null
+          and ${table.completedAt} is null
+        ) or (
+          ${table.status} = 'completed'
+          and ${table.claimHolderId} is null
+          and ${table.claimExpiresAt} is null
+          and ${table.slackChannelId} is not null
+          and ${table.slackMessageTimestamp} is not null
+          and ${table.completedAt} is not null
+        )`,
+    ),
+  }),
+);
+
 // OAuth client registrations minted through MCP DCR, keyed by authorization
 // server issuer. This is deployment-wide client identity, not a workspace
 // credential; per-user/provider tokens still live only in connections.
@@ -916,6 +1024,10 @@ export const sessions = pgTable(
     // (manual|policy) lives in the migration; no FK (it describes the pin, not an
     // account).
     codexPinSource: text("codex_pin_source"),
+    // Frozen at create: remote_v2 (Codex remote compaction + Codex-only models)
+    // or portable (plaintext compaction + free provider switching). Existing
+    // rows backfill to portable. CHECK lives in the migration.
+    codexCompactionMode: text("codex_compaction_mode").notNull().default("portable"),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
     // Assigned by the database trigger whenever canonical updated_at activity
@@ -1473,6 +1585,8 @@ export const sessionTurns = pgTable(
     toolsProvided: boolean("tools_provided").notNull().default(false),
     model: text("model").notNull(),
     reasoningEffort: text("reasoning_effort").notNull(),
+    // Peer of model + reasoning_effort for Fast/priority inheritance.
+    latencyMode: text("latency_mode").notNull().default("standard"),
     sandboxBackend: text("sandbox_backend").notNull(),
     // Per-turn OS override. NULL = inherit the session's sandbox_os. CHECK-
     // constrained to the SandboxOs enum (or NULL) in migration 0018.
@@ -1519,6 +1633,10 @@ export const sessionTurns = pgTable(
     oneCurrentInference: uniqueIndex("session_turns_one_current_inference_uq")
       .on(table.workspaceId, table.sessionId)
       .where(sql`${table.status} in ('running','requires_action','recovering','waiting_capacity')`),
+    latencyModeValid: check(
+      "session_turns_latency_mode_check",
+      sql`${table.latencyMode} in ('standard', 'priority', 'fast')`,
+    ),
   }),
 );
 
@@ -1828,6 +1946,7 @@ export const composerDrafts = pgTable(
     toolsProvided: boolean("tools_provided").notNull().default(false),
     model: text("model").notNull(),
     reasoningEffort: text("reasoning_effort").notNull(),
+    latencyMode: text("latency_mode").notNull().default("standard"),
     sourceTurnId: uuid("source_turn_id"),
     sourceTurnVersion: integer("source_turn_version"),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
@@ -1859,6 +1978,10 @@ export const composerDrafts = pgTable(
       sql`length(btrim(${table.subjectId})) > 0`,
     ),
     revisionValid: check("composer_drafts_revision_check", sql`${table.revision} >= 1`),
+    latencyModeValid: check(
+      "composer_drafts_latency_mode_check",
+      sql`${table.latencyMode} in ('standard', 'priority', 'fast')`,
+    ),
   }),
 );
 
@@ -1877,6 +2000,7 @@ export const newSessionDrafts = pgTable(
     tools: jsonb("tools").$type<unknown[]>().notNull().default([]),
     model: text("model").notNull(),
     reasoningEffort: text("reasoning_effort").notNull(),
+    latencyMode: text("latency_mode").notNull().default("standard"),
     sessionOptions: jsonb("session_options").$type<Record<string, unknown>>().notNull().default({}),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
@@ -1896,6 +2020,10 @@ export const newSessionDrafts = pgTable(
       sql`length(btrim(${table.subjectId})) > 0`,
     ),
     revisionValid: check("new_session_drafts_revision_check", sql`${table.revision} >= 1`),
+    latencyModeValid: check(
+      "new_session_drafts_latency_mode_check",
+      sql`${table.latencyMode} in ('standard', 'priority', 'fast')`,
+    ),
   }),
 );
 
@@ -2322,6 +2450,14 @@ export const agentRunStates = pgTable("agent_run_states", {
   // correct either way). NULL on both sides (non-codex freeze + non-codex
   // resume) is a no-op, so single-account and non-codex sessions are unchanged.
   frozenCodexCredentialId: uuid("frozen_codex_credential_id"),
+  // Exact provider rejection invalidates only the opaque reasoning identity
+  // inside this frozen state. The serialized receipt remains durable and
+  // auditable; the resume path neutralizes its provider-bound identity.
+  providerArtifactInvalidatedAt: timestamp("provider_artifact_invalidated_at", {
+    withTimezone: true,
+  }),
+  providerArtifactInvalidationReason: text("provider_artifact_invalidation_reason"),
+  providerArtifactInvalidatedByAttemptId: uuid("provider_artifact_invalidated_by_attempt_id"),
   createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
 });
 
@@ -2451,6 +2587,16 @@ export const sessionHistoryItems = pgTable(
     // (an ON DELETE SET NULL would erase the tag, and a stale-but-null tag still
     // mismatches a live codex id so the strip stays correct either way).
     producerCodexCredentialId: uuid("producer_codex_credential_id"),
+    // An exact provider 400 can prove that an otherwise same-credential opaque
+    // reasoning artifact is no longer decryptable. Keep the original item and
+    // producer provenance immutable, but record the attempt-fenced rejection so
+    // later model reads omit only the provider-bound identity. No FK: the receipt
+    // must outlive operational attempt retention just like producer provenance.
+    providerArtifactInvalidatedAt: timestamp("provider_artifact_invalidated_at", {
+      withTimezone: true,
+    }),
+    providerArtifactInvalidationReason: text("provider_artifact_invalidation_reason"),
+    providerArtifactInvalidatedByAttemptId: uuid("provider_artifact_invalidated_by_attempt_id"),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
   },
   (table) => ({
@@ -2543,6 +2689,134 @@ export const sandboxSessionEnvelopes = pgTable(
   }),
 );
 
+export const sandboxCheckpointArtifactStateValues = [
+  "candidate",
+  "current",
+  "previous",
+  "delete_pending",
+  "deleting",
+  "delete_failed",
+  "deleted",
+] as const;
+
+/**
+ * Durable ownership ledger for provider-native workspace checkpoints. These
+ * rows intentionally have no cascading parent FK: a workspace/lease can vanish
+ * before the provider object is deleted, and global GC still needs the exact
+ * non-secret provider binding and object id after that deletion.
+ */
+export const sandboxCheckpointArtifacts = pgTable(
+  "sandbox_checkpoint_artifacts",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    sandboxGroupId: uuid("sandbox_group_id").notNull(),
+    sourceLeaseId: uuid("source_lease_id").notNull(),
+    sourceLeaseEpoch: integer("source_lease_epoch").notNull(),
+    sourceInstanceId: text("source_instance_id"),
+    sourceWorkspaceGeneration: integer("source_workspace_generation"),
+    provenance: text("provenance", {
+      enum: ["native_capture", "legacy_provider_adopted"],
+    }).notNull(),
+    providerBackend: text("provider_backend").notNull(),
+    providerBindingKey: text("provider_binding_key").notNull(),
+    providerBinding: jsonb("provider_binding").$type<Record<string, unknown>>().notNull(),
+    objectKind: text("object_kind", {
+      enum: ["modal_filesystem_snapshot", "modal_directory_snapshot"],
+    }).notNull(),
+    objectId: text("object_id").notNull(),
+    archiveBase64: text("archive_base64").notNull(),
+    archiveSha256: text("archive_sha256").notNull(),
+    archiveBytes: integer("archive_bytes").notNull(),
+    descriptor: jsonb("descriptor").$type<Record<string, unknown>>().notNull(),
+    descriptorRevision: text("descriptor_revision").notNull(),
+    state: text("state", { enum: sandboxCheckpointArtifactStateValues })
+      .notNull()
+      .default("candidate"),
+    deleteAfter: timestamp("delete_after", { withTimezone: true }),
+    deleteAttempts: integer("delete_attempts").notNull().default(0),
+    deleteClaimId: uuid("delete_claim_id"),
+    deleteClaimedAt: timestamp("delete_claimed_at", { withTimezone: true }),
+    lastDeleteError: text("last_delete_error"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    publishedAt: timestamp("published_at", { withTimezone: true }),
+    deletedAt: timestamp("deleted_at", { withTimezone: true }),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    providerObject: uniqueIndex("sandbox_checkpoint_artifacts_provider_object_uq").on(
+      table.providerBackend,
+      table.providerBindingKey,
+      table.objectId,
+    ),
+    gc: index("sandbox_checkpoint_artifacts_gc_idx")
+      .on(table.deleteAfter, table.createdAt, table.id)
+      .where(
+        sql`${table.state} in (
+          'candidate', 'current', 'previous',
+          'delete_pending', 'delete_failed', 'deleting'
+        )`,
+      ),
+    source: index("sandbox_checkpoint_artifacts_source_idx").on(
+      table.workspaceId,
+      table.sandboxGroupId,
+      table.sourceLeaseId,
+    ),
+    sourceValid: check(
+      "sandbox_checkpoint_artifacts_source_check",
+      sql`${table.sourceLeaseEpoch} >= 0
+        and (
+          (
+            ${table.provenance} = 'native_capture'
+            and ${table.sourceWorkspaceGeneration} is not null
+            and ${table.sourceWorkspaceGeneration} >= 0
+            and ${table.sourceInstanceId} is not null
+            and octet_length(${table.sourceInstanceId}) between 1 and 512
+          )
+          or (
+            ${table.provenance} = 'legacy_provider_adopted'
+            and ${table.sourceWorkspaceGeneration} is null
+            and ${table.sourceInstanceId} is null
+          )
+        )`,
+    ),
+    providerValid: check(
+      "sandbox_checkpoint_artifacts_provider_check",
+      sql`${table.providerBackend} = 'modal'
+        and octet_length(${table.providerBindingKey}) between 1 and 1024
+        and jsonb_typeof(${table.providerBinding}) = 'object'
+        and ${table.providerBindingKey}::jsonb = ${table.providerBinding}
+        and ${table.objectKind} in ('modal_filesystem_snapshot', 'modal_directory_snapshot')
+        and octet_length(${table.objectId}) between 1 and 1024`,
+    ),
+    archiveValid: check(
+      "sandbox_checkpoint_artifacts_archive_check",
+      sql`${table.archiveBytes} > 0
+        and octet_length(${table.archiveBase64}) > 0
+        and ${table.archiveSha256} ~ '^[0-9a-f]{64}$'
+        and jsonb_typeof(${table.descriptor}) = 'object'
+        and octet_length(${table.descriptorRevision}) between 1 and 256`,
+    ),
+    stateValid: check(
+      "sandbox_checkpoint_artifacts_state_check",
+      sql`${table.state} in (
+        'candidate', 'current', 'previous', 'delete_pending',
+        'deleting', 'delete_failed', 'deleted'
+      )`,
+    ),
+    deleteClaimValid: check(
+      "sandbox_checkpoint_artifacts_delete_claim_check",
+      sql`(${table.state} = 'deleting'
+          and ${table.deleteClaimId} is not null
+          and ${table.deleteClaimedAt} is not null)
+        or (${table.state} <> 'deleting'
+          and ${table.deleteClaimId} is null
+          and ${table.deleteClaimedAt} is null)`,
+    ),
+  }),
+);
+
 // The 4 liveness states of the singleton lease. Exported so the query layer and
 // the stateless resume-by-id path share one source of truth for the domain.
 export const sandboxLeaseLivenessValues = ["cold", "warming", "warm", "draining"] as const;
@@ -2578,14 +2852,14 @@ export const sandboxLeases = pgTable(
     // The container IMAGE the group box runs (Modal image ref / docker image). A shared
     // box is SHARED STATE: all its sessions run the SAME filesystem, so they must run the
     // same image. This column stamps the image the live box was created with; a resume
-    // whose resolved image DIFFERS is a conflict (B3): a solo holder recreates the box on
-    // the new image, N-holders are rejected (SandboxImageConflictError). Nullable — a
+    // whose resolved image DIFFERS is a conflict (B3): a solo holder requests a
+    // capture-and-drain rotation; N-holders are rejected (SandboxImageConflictError). Nullable — a
     // legacy/cold row reads NULL = "image unknown", which never conflicts.
     image: text("image"),
     // The frozen rig version the live box was created under (M3). Like `image`,
     // this is SHARED STATE: all the box's sessions run the same rig-baked setup,
-    // so a resume resolving a DIFFERENT rig_version_id conflicts (solo holder
-    // recreates cold on the new rig; N-holders throw SandboxRigConflictError).
+    // so a resume resolving a DIFFERENT rig_version_id conflicts (a solo holder
+    // requests capture-and-drain rotation; N-holders throw SandboxRigConflictError).
     // Nullable — a legacy/cold row or a rig-less session reads NULL = "rig
     // unknown", which never conflicts. No FK (symmetric with sandbox_group_id's
     // bare-uuid rationale: this lease outlives no single rig_versions row's RLS).
@@ -2611,6 +2885,19 @@ export const sandboxLeases = pgTable(
     // the same row update; equality is the only durable completeness proof.
     workspaceGeneration: integer("workspace_generation").notNull().default(0),
     archiveGeneration: integer("archive_generation"),
+    // Provider-native capture may pause the live box. The exact claim is
+    // acquired before provider I/O and cleared only after that capture settles;
+    // new holders and workspace mutations fence on it. The SQL constraint also
+    // requires the claimed generation to remain current, so an unaware writer
+    // cannot advance generation through an active capture.
+    archiveCaptureId: uuid("archive_capture_id"),
+    archiveCaptureGeneration: integer("archive_capture_generation"),
+    archiveCaptureStartedAt: timestamp("archive_capture_started_at", {
+      withTimezone: true,
+    }),
+    archiveCaptureDeadlineAt: timestamp("archive_capture_deadline_at", {
+      withTimezone: true,
+    }),
 
     // The group box-envelope (the "envelope split" Critical): the small recovery
     // descriptor to resume()-by-id the group's box without a per-session join.
@@ -2623,6 +2910,18 @@ export const sandboxLeases = pgTable(
     lastMeterAt: timestamp("last_meter_at", { withTimezone: true }),
     lastMeterTick: integer("last_meter_tick").notNull().default(0),
 
+    providerCreatedAt: timestamp("provider_created_at", { withTimezone: true }),
+    providerDeadlineAt: timestamp("provider_deadline_at", { withTimezone: true }),
+    rotationRequestedAt: timestamp("rotation_requested_at", { withTimezone: true }),
+    rotationReason: text("rotation_reason", {
+      enum: ["provider_deadline", "operator"],
+    }),
+    // The SQL migration owns the two DEFERRABLE foreign keys and deferred
+    // scope/state constraint triggers. Drizzle does not model deferrability, so
+    // these remain bare UUIDs here rather than generating a stricter wrong FK.
+    currentCheckpointArtifactId: uuid("current_checkpoint_artifact_id"),
+    previousCheckpointArtifactId: uuid("previous_checkpoint_artifact_id"),
+
     expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
@@ -2646,6 +2945,13 @@ export const sandboxLeases = pgTable(
     expiredDrainingInventory: index("sandbox_leases_expired_draining_inventory_idx")
       .on(table.expiresAt, table.backend)
       .where(sql`${table.liveness} = 'draining'`),
+    providerDeadline: index("sandbox_leases_provider_deadline_idx")
+      .on(table.providerDeadlineAt, table.id)
+      .where(
+        sql`${table.backend} = 'modal'
+          and ${table.liveness} in ('warming', 'warm')
+          and ${table.rotationRequestedAt} is null`,
+      ),
     workspaceGenerationValid: check(
       "sandbox_leases_workspace_generation_check",
       sql`${table.workspaceGeneration} >= 0`,
@@ -2656,6 +2962,43 @@ export const sandboxLeases = pgTable(
         or (${table.archiveGeneration} >= 0
           and ${table.archiveGeneration} <= ${table.workspaceGeneration})`,
     ),
+    archiveCaptureValid: check(
+      "sandbox_leases_archive_capture_check",
+      sql`(
+          ${table.archiveCaptureId} is null
+          and ${table.archiveCaptureGeneration} is null
+          and ${table.archiveCaptureStartedAt} is null
+          and ${table.archiveCaptureDeadlineAt} is null
+        ) or (
+          ${table.archiveCaptureId} is not null
+          and ${table.archiveCaptureGeneration} is not null
+          and ${table.archiveCaptureGeneration} = ${table.workspaceGeneration}
+          and ${table.archiveCaptureStartedAt} is not null
+          and ${table.archiveCaptureDeadlineAt} > ${table.archiveCaptureStartedAt}
+        )`,
+    ),
+    archiveCaptureDeadline: index("sandbox_leases_archive_capture_deadline_idx")
+      .on(table.archiveCaptureDeadlineAt, table.id)
+      .where(sql`${table.archiveCaptureId} is not null`),
+    providerDeadlineValid: check(
+      "sandbox_leases_provider_deadline_check",
+      sql`(${table.providerCreatedAt} is null and ${table.providerDeadlineAt} is null)
+        or (${table.providerCreatedAt} is not null
+          and ${table.providerDeadlineAt} is not null
+          and ${table.providerDeadlineAt} > ${table.providerCreatedAt})`,
+    ),
+    rotationValid: check(
+      "sandbox_leases_rotation_check",
+      sql`(${table.rotationRequestedAt} is null and ${table.rotationReason} is null)
+        or (${table.rotationRequestedAt} is not null
+          and ${table.rotationReason} in ('provider_deadline', 'operator'))`,
+    ),
+    checkpointDistinct: check(
+      "sandbox_leases_checkpoint_distinct_check",
+      sql`${table.currentCheckpointArtifactId} is null
+        or ${table.previousCheckpointArtifactId} is null
+        or ${table.currentCheckpointArtifactId} <> ${table.previousCheckpointArtifactId}`,
+    ),
   }),
 );
 
@@ -2874,6 +3217,11 @@ export const sandboxRetainedProcesses = pgTable(
     leaseEpoch: integer("lease_epoch").notNull(),
     providerBackend: text("provider_backend").notNull(),
     providerInstanceId: text("provider_instance_id").notNull(),
+    // Provider object ids are namespace-scoped. New Modal processes bind the
+    // exact authenticated workspace before execution; legacy rows remain null
+    // until a positive lookup proves which namespace owns the historical box.
+    providerBindingKey: text("provider_binding_key"),
+    providerBinding: jsonb("provider_binding").$type<Record<string, unknown>>(),
     routeKind: text("route_kind", { enum: ["home", "active"] }).notNull(),
     routeTargetId: uuid("route_target_id"),
     routeEpoch: integer("route_epoch").notNull(),
@@ -2990,6 +3338,33 @@ export const sandboxRetainedProcesses = pgTable(
       sql`${table.settlementReason} is null
         or octet_length(${table.settlementReason}) between 1 and 512`,
     ),
+    providerBindingValid: check(
+      "sandbox_retained_processes_provider_binding_check",
+      sql`(
+          ${table.providerBindingKey} is null
+          and ${table.providerBinding} is null
+        ) or (
+          ${table.providerBackend} = 'modal'
+          and octet_length(${table.providerBindingKey}) between 1 and 1024
+          and jsonb_typeof(${table.providerBinding}) = 'object'
+          and ${table.providerBindingKey}::jsonb = ${table.providerBinding}
+          and ${table.providerBindingKey} = format(
+            '{"version":1,"serverUrl":%s,"workspaceName":%s,"environment":%s}',
+            to_jsonb(${table.providerBinding} ->> 'serverUrl')::text,
+            to_jsonb(${table.providerBinding} ->> 'workspaceName')::text,
+            to_jsonb(${table.providerBinding} ->> 'environment')::text
+          )
+          and ${table.providerBinding} = jsonb_build_object(
+            'version', 1,
+            'serverUrl', ${table.providerBinding} ->> 'serverUrl',
+            'workspaceName', ${table.providerBinding} ->> 'workspaceName',
+            'environment', ${table.providerBinding} ->> 'environment'
+          )
+          and coalesce(octet_length(${table.providerBinding} ->> 'serverUrl'), 0) > 0
+          and coalesce(octet_length(${table.providerBinding} ->> 'workspaceName'), 0) > 0
+          and ${table.providerBinding} ->> 'environment' is not null
+        )`,
+    ),
     reconcileClaimValid: check(
       "sandbox_retained_processes_reconcile_claim_check",
       sql`(${table.reconcileClaimId} is null and ${table.reconcileClaimedAt} is null)
@@ -3020,7 +3395,8 @@ export const sandboxRetainedProcesses = pgTable(
           ${table.reconcileProofOutcome} = 'lost'
           and ${table.reconcileProofExitCode} is null
           and ${table.reconcileProofReason} in (
-            'provider_session_lost_banner', 'provider_instance_not_found'
+            'provider_session_lost_banner', 'provider_instance_not_found',
+            'provider_instance_terminated'
           )
           and ${table.reconcileProofObservedAt} is not null
         )`,
@@ -3805,6 +4181,102 @@ export const usageEvents = pgTable(
   }),
 );
 
+/**
+ * Per model-call Insights facts. Additive observability only — never the billing
+ * ledger. Written after an authoritative `agent.model.usage` emit.
+ */
+export const modelCallFacts = pgTable(
+  "model_call_facts",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id")
+      .notNull()
+      .references(() => managedAccounts.id, { onDelete: "cascade" }),
+    workspaceId: uuid("workspace_id")
+      .notNull()
+      .references(() => workspaces.id, { onDelete: "cascade" }),
+    sessionId: uuid("session_id").notNull(),
+    turnId: uuid("turn_id").notNull(),
+    turnAttemptId: uuid("turn_attempt_id"),
+    sourceKey: text("source_key").notNull(),
+    provider: text("provider").notNull(),
+    providerApi: text("provider_api").notNull(),
+    model: text("model").notNull(),
+    billingPath: text("billing_path").notNull(),
+    turnSource: text("turn_source"),
+    initiatorKind: text("initiator_kind"),
+    initiatorSubjectId: text("initiator_subject_id"),
+    scheduledTaskId: uuid("scheduled_task_id"),
+    inputTokens: bigint("input_tokens", { mode: "number" }),
+    outputTokens: bigint("output_tokens", { mode: "number" }),
+    cachedTokens: bigint("cached_tokens", { mode: "number" }),
+    cacheWriteTokens: bigint("cache_write_tokens", { mode: "number" }),
+    reasoningTokens: bigint("reasoning_tokens", { mode: "number" }),
+    totalTokens: bigint("total_tokens", { mode: "number" }),
+    pricedCostMicros: bigint("priced_cost_micros", { mode: "number" }).notNull().default(0),
+    occurredAt: timestamp("occurred_at", { withTimezone: true }).notNull(),
+    recordedAt: timestamp("recorded_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    workspaceTurnSource: uniqueIndex("model_call_facts_workspace_turn_source_uq").on(
+      table.workspaceId,
+      table.turnId,
+      table.sourceKey,
+    ),
+    workspaceOccurred: index("model_call_facts_workspace_occurred_idx").on(
+      table.workspaceId,
+      table.occurredAt,
+    ),
+    workspaceProviderModelOccurred: index(
+      "model_call_facts_workspace_provider_model_occurred_idx",
+    ).on(table.workspaceId, table.provider, table.model, table.occurredAt),
+    workspaceSessionOccurred: index("model_call_facts_workspace_session_occurred_idx").on(
+      table.workspaceId,
+      table.sessionId,
+      table.occurredAt,
+    ),
+    workspaceScheduledTaskOccurred: index("model_call_facts_workspace_scheduled_task_occurred_idx")
+      .on(table.workspaceId, table.scheduledTaskId, table.occurredAt)
+      .where(sql`${table.scheduledTaskId} is not null`),
+    workspaceAccount: foreignKey({
+      name: "model_call_facts_workspace_account_fk",
+      columns: [table.workspaceId, table.accountId],
+      foreignColumns: [workspaces.id, workspaces.accountId],
+    }).onDelete("cascade"),
+    billingPathValid: check(
+      "model_call_facts_billing_path_check",
+      sql`${table.billingPath} in ('opengeni_credits', 'external')`,
+    ),
+    pricedCostNonNegative: check(
+      "model_call_facts_priced_cost_check",
+      sql`${table.pricedCostMicros} >= 0`,
+    ),
+    initiatorConsistent: check(
+      "model_call_facts_initiator_check",
+      sql`(${table.initiatorKind} is null and ${table.initiatorSubjectId} is null)
+        or (${table.initiatorKind} in ('subject', 'service')
+          and ${table.initiatorSubjectId} is not null
+          and octet_length(${table.initiatorSubjectId}) between 1 and 1024)`,
+    ),
+    sourceKeyBytes: check(
+      "model_call_facts_source_key_bytes_check",
+      sql`octet_length(${table.sourceKey}) between 1 and 1024`,
+    ),
+    providerBytes: check(
+      "model_call_facts_provider_bytes_check",
+      sql`octet_length(${table.provider}) between 1 and 256`,
+    ),
+    providerApiBytes: check(
+      "model_call_facts_provider_api_bytes_check",
+      sql`octet_length(${table.providerApi}) between 1 and 256`,
+    ),
+    modelBytes: check(
+      "model_call_facts_model_bytes_check",
+      sql`octet_length(${table.model}) between 1 and 512`,
+    ),
+  }),
+);
+
 /** Singleton, migration-installed gate. Standalone defaults keep both off. */
 export const hostExportConfig = pgTable(
   "host_export_config",
@@ -4439,3 +4911,4 @@ export const rigChanges = pgTable(
 );
 
 export * from "./workspace-instruction-policies-schema";
+export * from "./preference-registry-schema";