@opengeni/db 0.7.3 → 0.9.3

package/src/schema.ts

@@ -1,4 +1,6 @@
+import type { McpServerConnectionRef } from "@opengeni/contracts";
 import { sql } from "drizzle-orm";
+import type { HumanInputQuestion, HumanInputResponse } from "@opengeni/contracts";
 import {
   bigint,
   boolean,
@@ -88,7 +90,9 @@ export const workspaceInferenceControls = pgTable(
     accountId: uuid("account_id").notNull(),
     revision: bigint("revision", { mode: "number" }).notNull().default(0),
     workspaceState: text("workspace_state").notNull().default("active"),
-    workspacePauseRevision: bigint("workspace_pause_revision", { mode: "number" }),
+    workspacePauseRevision: bigint("workspace_pause_revision", {
+      mode: "number",
+    }),
     reason: text("reason"),
     changedBy: text("changed_by"),
     changedAt: timestamp("changed_at", { withTimezone: true }),
@@ -121,6 +125,30 @@ export const workspaceInferenceControls = pgTable(
   }),
 );
 
+// One transactionally allocated activity clock per workspace. An updated-order
+// first page takes a SHARE lock on this row after the workspace-control lock;
+// semantic writers allocate after UUID-ordered session locks. Plain MVCC page
+// reads never lock session rows, so that ordering cannot form a cycle.
+export const workspaceSessionActivityRevisions = pgTable(
+  "workspace_session_activity_revisions",
+  {
+    workspaceId: uuid("workspace_id").primaryKey(),
+    accountId: uuid("account_id").notNull(),
+    revision: bigint("revision", { mode: "number" }).notNull().default(0),
+  },
+  (table) => ({
+    workspaceAccount: foreignKey({
+      name: "workspace_session_activity_revisions_workspace_account_fk",
+      columns: [table.workspaceId, table.accountId],
+      foreignColumns: [workspaces.id, workspaces.accountId],
+    }).onDelete("cascade"),
+    revisionValid: check(
+      "workspace_session_activity_revisions_revision_check",
+      sql`${table.revision} >= 0`,
+    ),
+  }),
+);
+
 export const workspaceMemberships = pgTable(
   "workspace_memberships",
   {
@@ -155,7 +183,9 @@ export const apiKeys = pgTable(
     accountId: uuid("account_id")
       .notNull()
       .references(() => managedAccounts.id, { onDelete: "cascade" }),
-    workspaceId: uuid("workspace_id").references(() => workspaces.id, { onDelete: "cascade" }),
+    workspaceId: uuid("workspace_id").references(() => workspaces.id, {
+      onDelete: "cascade",
+    }),
     name: text("name").notNull(),
     prefix: text("prefix").notNull(),
     keyHash: text("key_hash").notNull(),
@@ -280,13 +310,15 @@ export const codexSubscriptionCredentials = pgTable(
     // excluded). The writer only ever sets a NON-empty set, so a flaky empty turn
     // can't false-drop coverage. connectorsCheckedAt is the freshness clock.
     connectorNamespaces: text("connector_namespaces").array(),
-    connectorsCheckedAt: timestamp("connectors_checked_at", { withTimezone: true }),
+    connectorsCheckedAt: timestamp("connectors_checked_at", {
+      withTimezone: true,
+    }),
     // Workspace-local, server-held fairness cursor. Provider usage headers are
     // capacity hints, never the sole allocator: live lease count is ranked first
     // and this cursor deterministically breaks equal-load/equal-capacity ties.
     // This flag controls NEW automatic allocations only. Credential health,
     // refresh, encrypted material, and already-frozen/in-flight turns are
-    // intentionally independent. OPE-24 owns toggle OCC/audit and product UI.
+    // intentionally independent. account eligibility policy owns toggle OCC/audit and product UI.
     allocatorEnabled: boolean("allocator_enabled").notNull().default(true),
     selectionCount: integer("selection_count").notNull().default(0),
     lastSelectedAt: timestamp("last_selected_at", { withTimezone: true }),
@@ -432,7 +464,7 @@ export const codexRotationSettings = pgTable(
     // code reads this bit; old binaries safely ignore it and keep the legacy
     // pin/rotation policy.
     leaseRotationEnabled: boolean("lease_rotation_enabled").notNull().default(false),
-    rotationStrategy: text("rotation_strategy").notNull().default("most_remaining"), // P3, inert
+    rotationStrategy: text("rotation_strategy").notNull().default("sharded"), // sharded-rotation policy: legacy residue; behavior is always sharded
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
   },
@@ -527,6 +559,10 @@ export const sessions = pgTable(
       .references(() => workspaces.id, { onDelete: "cascade" }),
     status: text("status").notNull().default("queued"),
     initialMessage: text("initial_message").notNull(),
+    // Invisible host context frozen with the winning session create. The
+    // initial turn copies this value so an idempotent repair can never adopt a
+    // retrying caller's different instructions.
+    initialTurnInstructions: text("initial_turn_instructions"),
     title: text("title"),
     titleSource: text("title_source"),
     // Per-session agent persona/system instructions supplied at create (the
@@ -539,6 +575,14 @@ export const sessions = pgTable(
     resources: jsonb("resources").$type<unknown[]>().notNull().default([]),
     tools: jsonb("tools").$type<unknown[]>().notNull().default([]),
     metadata: jsonb("metadata").$type<Record<string, unknown>>().notNull().default({}),
+    // Frozen creator fact. This is used for creation attribution and for the
+    // idempotent first-turn repair only; later turns capture their own actor.
+    createdByKind: text("created_by_kind").notNull().default("service"),
+    createdBySubjectId: text("created_by_subject_id").notNull().default("unattributed-legacy"),
+    createdByContext: jsonb("created_by_context")
+      .$type<Record<string, unknown>>()
+      .notNull()
+      .default({ backfill: true }),
     model: text("model").notNull(),
     sandboxBackend: text("sandbox_backend").notNull(),
     // The OS this session's box runs. Defaults to 'linux' (today's only OS, so
@@ -554,8 +598,8 @@ export const sessions = pgTable(
     // The app generates the uuid and uses it for both id and sandbox_group_id in
     // one insert — it cannot SQL-default to id (id is defaultRandom()).
     sandboxGroupId: uuid("sandbox_group_id").notNull(),
-    // The first-class swappable-sandbox POINTER (bring-your-own-compute M2,
-    // dossier §10.3). NULL == "use the session's own group sandbox" (the
+    // The first-class swappable-sandbox POINTER (bring-your-own-compute M2).
+    // NULL == "use the session's own group sandbox" (the
     // backward-compat default — every existing/new row is a behavior-preserving
     // no-op). The routing proxy re-reads (active_sandbox_id, active_epoch) PER
     // TOOL CALL to make a Modal<->selfhosted hot-swap seamless. The FK
@@ -620,11 +664,15 @@ export const sessions = pgTable(
     queueTailPosition: bigint("queue_tail_position", { mode: "number" }).notNull().default(0),
     directControlState: text("direct_control_state").notNull().default("active"),
     directPauseRevision: bigint("direct_pause_revision", { mode: "number" }),
-    subtreeRunOverrideRevision: bigint("subtree_run_override_revision", { mode: "number" }),
+    subtreeRunOverrideRevision: bigint("subtree_run_override_revision", {
+      mode: "number",
+    }),
     controlVersion: bigint("control_version", { mode: "number" }).notNull().default(0),
     directControlReason: text("direct_control_reason"),
     directControlChangedBy: text("direct_control_changed_by"),
-    directControlChangedAt: timestamp("direct_control_changed_at", { withTimezone: true }),
+    directControlChangedAt: timestamp("direct_control_changed_at", {
+      withTimezone: true,
+    }),
     lastSequence: integer("last_sequence").notNull().default(0),
     // The session's PINNED Codex account (manual override from the in-session
     // switcher). NULL ⇒ follow the workspace active pointer. FK declared in the
@@ -645,6 +693,10 @@ export const sessions = pgTable(
     codexPinSource: text("codex_pin_source"),
     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
+    // advances. Legacy rows remain zero until touched; raw delta-only writers
+    // intentionally omit updated_at and therefore do not allocate revisions.
+    activityRevision: bigint("activity_revision", { mode: "number" }).notNull().default(0),
   },
   (table) => ({
     workspaceIdentity: uniqueIndex("sessions_workspace_id_idx").on(table.workspaceId, table.id),
@@ -652,6 +704,25 @@ export const sessions = pgTable(
       table.workspaceId,
       table.createdAt,
     ),
+    // Model-facing monitoring pages use exact (timestamp,id) keysets. Keep the
+    // older prefix index during rolling deploys; these composites serve both
+    // deterministic traversal and updatedAfter change scans.
+    workspaceCreatedId: index("sessions_workspace_created_id_idx").on(
+      table.workspaceId,
+      table.createdAt.desc(),
+      table.id.desc(),
+    ),
+    workspaceUpdatedId: index("sessions_workspace_updated_id_idx").on(
+      table.workspaceId,
+      table.updatedAt.desc(),
+      table.id.desc(),
+    ),
+    workspaceActivityRevision: index("sessions_workspace_activity_revision_idx").on(
+      table.workspaceId,
+      table.activityRevision.desc(),
+      table.updatedAt.desc(),
+      table.id.desc(),
+    ),
     variableSet: index("sessions_variable_set_idx").on(table.workspaceId, table.variableSetId),
     parent: index("sessions_parent_idx").on(table.workspaceId, table.parentSessionId),
     // Routing index: resolve session_id -> sandbox_group_id at every lease entry
@@ -801,6 +872,9 @@ export const sessionMcpServers = pgTable(
     // Human-approval policy: `true` = every tool requires approval, a string[] of
     // UNPREFIXED tool names = only those require it, null/absent = auto-run.
     requireApproval: jsonb("require_approval").$type<boolean | string[]>(),
+    // Non-secret pointer resolved at request time by the standalone broker or
+    // an embedding host. Unlike headersEncrypted, this is safe to project.
+    connectionRef: jsonb("connection_ref").$type<McpServerConnectionRef>(),
     // Map of header name -> AES-GCM ciphertext. Values are decrypted only by the
     // worker's run-preparation path and never returned by API helpers.
     headersEncrypted: jsonb("headers_encrypted")
@@ -1077,6 +1151,9 @@ export const sessionTurns = pgTable(
     source: text("source").notNull().default("user"),
     position: bigint("position", { mode: "number" }).notNull(),
     prompt: text("prompt").notNull(),
+    // Host context for this exact turn. System-level at runtime and deliberately
+    // separate from the visible prompt/event payload.
+    turnInstructions: text("turn_instructions"),
     resources: jsonb("resources").$type<unknown[]>().notNull().default([]),
     tools: jsonb("tools").$type<unknown[]>().notNull().default([]),
     model: text("model").notNull(),
@@ -1094,6 +1171,14 @@ export const sessionTurns = pgTable(
     // the SQL constraint is therefore DEFERRABLE INITIALLY DEFERRED.
     activeAttemptId: uuid("active_attempt_id"),
     lineage: jsonb("lineage").$type<Record<string, unknown>>().notNull().default({}),
+    // Required immutable authority captured when the turn is accepted. These
+    // columns are deliberately outside mutable metadata/lineage.
+    initiatorKind: text("initiator_kind").notNull().default("service"),
+    initiatorSubjectId: text("initiator_subject_id").notNull().default("unattributed-legacy"),
+    initiatorContext: jsonb("initiator_context")
+      .$type<Record<string, unknown>>()
+      .notNull()
+      .default({ backfill: true }),
     cancelledBy: text("cancelled_by"),
     cancelReason: text("cancel_reason"),
     // Atomic per-turn toolspace call budget counter (migration 0043). Incremented
@@ -1142,10 +1227,18 @@ export const sessionTurnAttempts = pgTable(
     workerId: text("worker_id"),
     leaseId: text("lease_id"),
     leaseExpiresAt: timestamp("lease_expires_at", { withTimezone: true }),
-    verifiedControlRevision: bigint("verified_control_revision", { mode: "number" }).notNull(),
+    verifiedControlRevision: bigint("verified_control_revision", {
+      mode: "number",
+    }).notNull(),
     startedAt: timestamp("started_at", { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
     closedAt: timestamp("closed_at", { withTimezone: true }),
+    // The cancelled activity writes this after losing inference, user-visible
+    // output, and workspace-persistence authority. Fenced/idempotent cleanup
+    // and telemetry may still finish. Temporal activity cancellation or
+    // terminalization is transport state only; queue admission and clients use
+    // this durable receipt as the physical-quiescence authority.
+    quiescedAt: timestamp("quiesced_at", { withTimezone: true }),
   },
   (table) => ({
     workspaceAccount: foreignKey({
@@ -1167,12 +1260,25 @@ export const sessionTurnAttempts = pgTable(
       table.workspaceId,
       table.id,
     ),
+    ownershipIdentity: uniqueIndex("session_turn_attempts_human_input_owner_uq").on(
+      table.accountId,
+      table.workspaceId,
+      table.sessionId,
+      table.turnId,
+      table.id,
+    ),
     liveTurn: uniqueIndex("session_turn_attempts_live_turn_uq")
       .on(table.workspaceId, table.turnId)
       .where(sql`${table.state} in ('claimed', 'running')`),
     liveSession: uniqueIndex("session_turn_attempts_live_session_uq")
       .on(table.workspaceId, table.sessionId)
       .where(sql`${table.state} in ('claimed', 'running')`),
+    latestSessionAttempt: index("session_turn_attempts_latest_session_idx").on(
+      table.workspaceId,
+      table.sessionId,
+      table.startedAt.desc(),
+      table.id.desc(),
+    ),
     dispatch: uniqueIndex("session_turn_attempts_dispatch_uq").on(
       table.workspaceId,
       table.temporalWorkflowRunId,
@@ -1217,7 +1323,9 @@ export const sessionCommandReceipts = pgTable(
     targetTurnId: uuid("target_turn_id"),
     operationKey: text("operation_key").notNull(),
     canonicalRequestHash: text("canonical_request_hash").notNull(),
-    appliedControlRevision: bigint("applied_control_revision", { mode: "number" }),
+    appliedControlRevision: bigint("applied_control_revision", {
+      mode: "number",
+    }),
     appliedQueueVersion: integer("applied_queue_version"),
     appliedTurnVersion: integer("applied_turn_version"),
     appliedDraftRevision: bigint("applied_draft_revision", { mode: "number" }),
@@ -1262,7 +1370,7 @@ export const sessionCommandReceipts = pgTable(
         and ${table.actorAttemptId} is not null
         and ${table.actorSubjectId} is null
       ) or (
-        ${table.actorType} in ('human', 'operator')
+        ${table.actorType} in ('human', 'operator', 'service')
         and ${table.actorSubjectId} is not null
         and ${table.actorAttemptId} is null
       )`,
@@ -1286,7 +1394,11 @@ export const workspaceControlEvents = pgTable(
     action: text("action").notNull(),
     automatic: boolean("automatic").notNull().default(false),
     reason: text("reason"),
+    reasonOriginalBytes: integer("reason_original_bytes"),
     actor: text("actor").notNull(),
+    // Null is the rolling-upgrade shape for untouched, already-bounded legacy
+    // rows. New writes and rewritten poison rows carry exact source byte facts.
+    actorOriginalBytes: integer("actor_original_bytes"),
     occurredAt: timestamp("occurred_at", { withTimezone: true }).notNull().defaultNow(),
   },
   (table) => ({
@@ -1628,7 +1740,7 @@ export const sessionGoals = pgTable(
   }),
 );
 
-// OPE-21: one durable, coalescing capacity waiter per session. The row is both
+// credential allocator: one durable, coalescing capacity waiter per session. The row is both
 // the wait state and the commit->signal outbox: capacity mutations increment
 // wakeRevision in the SAME transaction as the mutation, while the session
 // workflow advances observedWakeRevision only after it has re-evaluated the
@@ -1638,7 +1750,7 @@ export const sessionGoals = pgTable(
 // The session/goal/turn foreign keys are declared in migration 0053 so the
 // table keeps the same composite workspace-integrity posture as credential
 // leases. Control is evaluated independently at admission and never changes a
-// capacity waiter's identity. OPE-32 supplies policyHash when accepted-turn
+// capacity waiter's identity. policy filter supplies policyHash when accepted-turn
 // pool routing lands.
 export const codexCapacityWaiters = pgTable(
   "codex_capacity_waiters",
@@ -1744,6 +1856,41 @@ export const sessionEvents = pgTable(
       table.sessionId,
       table.createdAt,
     ),
+    sessionTypeSequence: index("session_events_workspace_session_type_sequence_idx").on(
+      table.workspaceId,
+      table.sessionId,
+      table.type,
+      table.sequence,
+    ),
+    monitoringTail: index("session_events_workspace_session_monitoring_tail_idx")
+      .on(table.workspaceId, table.sessionId, table.sequence)
+      .where(
+        sql`${table.type} not in ('agent.message.delta', 'agent.reasoning.delta', 'sandbox.command.output.delta', 'terminal.pty.output.delta')`,
+      ),
+    payloadBytes: check(
+      "session_events_payload_bytes_check",
+      sql`octet_length(${table.payload}::text) <= 65536`,
+    ),
+    typeBytes: check(
+      "session_events_type_bytes_check",
+      sql`octet_length(${table.type}) <= 256 and position(E'\n' in ${table.type}) = 0 and position(E'\r' in ${table.type}) = 0`,
+    ),
+    clientEventIdBytes: check(
+      "session_events_client_event_id_bytes_check",
+      sql`${table.clientEventId} is null or octet_length(${table.clientEventId}) <= 1024`,
+    ),
+    producerIdBytes: check(
+      "session_events_producer_id_bytes_check",
+      sql`${table.producerId} is null or octet_length(${table.producerId}) <= 1024`,
+    ),
+    turnAssociationBytes: check(
+      "session_events_turn_association_bytes_check",
+      sql`${table.turnAssociation} is null or octet_length(${table.turnAssociation}) <= 64`,
+    ),
+    duplicateReasonBytes: check(
+      "session_events_duplicate_reason_bytes_check",
+      sql`${table.duplicateReason} is null or octet_length(${table.duplicateReason}) <= 4096`,
+    ),
   }),
 );
 
@@ -1758,7 +1905,9 @@ export const agentRunStates = pgTable("agent_run_states", {
   sessionId: uuid("session_id")
     .notNull()
     .references(() => sessions.id, { onDelete: "cascade" }),
-  turnId: uuid("turn_id").references(() => sessionTurns.id, { onDelete: "set null" }),
+  turnId: uuid("turn_id").references(() => sessionTurns.id, {
+    onDelete: "set null",
+  }),
   stateVersion: integer("state_version").notNull(),
   serializedRunState: text("serialized_run_state").notNull(),
   pendingApprovals: jsonb("pending_approvals").$type<unknown[]>().notNull().default([]),
@@ -1781,6 +1930,88 @@ export const agentRunStates = pgTable("agent_run_states", {
   createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
 });
 
+// Durable structured human-input requests. The creation attempt is immutable
+// provenance; legitimate resume attempts are newer owners of the SAME logical
+// turn. Settlement therefore fences on the active session/turn plus the
+// request's turn generation, never on creationAttemptId.
+export const sessionHumanInputRequests = pgTable(
+  "session_human_input_requests",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    sessionId: uuid("session_id").notNull(),
+    turnId: uuid("turn_id").notNull(),
+    turnGeneration: integer("turn_generation").notNull(),
+    creationAttemptId: uuid("creation_attempt_id").notNull(),
+    toolCallId: text("tool_call_id").notNull(),
+    status: text("status").notNull().default("pending"),
+    questions: jsonb("questions").$type<HumanInputQuestion[]>().notNull(),
+    allowSkip: boolean("allow_skip").notNull().default(false),
+    response: jsonb("response").$type<HumanInputResponse>(),
+    respondedBy: text("responded_by"),
+    respondedAt: timestamp("responded_at", { withTimezone: true }),
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    creationAttemptOwner: foreignKey({
+      name: "session_human_input_requests_creation_attempt_fk",
+      columns: [
+        table.accountId,
+        table.workspaceId,
+        table.sessionId,
+        table.turnId,
+        table.creationAttemptId,
+      ],
+      foreignColumns: [
+        sessionTurnAttempts.accountId,
+        sessionTurnAttempts.workspaceId,
+        sessionTurnAttempts.sessionId,
+        sessionTurnAttempts.turnId,
+        sessionTurnAttempts.id,
+      ],
+    }).onDelete("cascade"),
+    toolCall: uniqueIndex("session_human_input_requests_tool_call_uq").on(
+      table.workspaceId,
+      table.sessionId,
+      table.turnId,
+      table.toolCallId,
+    ),
+    pendingSession: index("session_human_input_requests_pending_session_idx")
+      .on(table.workspaceId, table.sessionId, table.createdAt, table.id)
+      .where(sql`${table.status} = 'pending'`),
+    pendingExpiry: index("session_human_input_requests_pending_expiry_idx")
+      .on(table.expiresAt, table.id)
+      .where(sql`${table.status} = 'pending' and ${table.expiresAt} is not null`),
+    status: check(
+      "session_human_input_requests_status_check",
+      sql`${table.status} in ('pending','answered','skipped','expired','cancelled')`,
+    ),
+    generation: check(
+      "session_human_input_requests_generation_check",
+      sql`${table.turnGeneration} > 0`,
+    ),
+    toolCallBytes: check(
+      "session_human_input_requests_tool_call_bytes_check",
+      sql`octet_length(${table.toolCallId}) between 1 and 1024`,
+    ),
+    questionsBytes: check(
+      "session_human_input_requests_questions_bytes_check",
+      sql`octet_length(${table.questions}::text) <= 49152`,
+    ),
+    responseBytes: check(
+      "session_human_input_requests_response_bytes_check",
+      sql`${table.response} is null or octet_length(${table.response}::text) <= 49152`,
+    ),
+    actorBytes: check(
+      "session_human_input_requests_actor_bytes_check",
+      sql`${table.respondedBy} is null or octet_length(${table.respondedBy}) <= 1024`,
+    ),
+  }),
+);
+
 // Conversation truth: ordered, verbatim SDK input items (issue #35). The
 // model-facing memory store — unredacted and replay-ready. session_events
 // remains the redacted human/audit timeline.
@@ -1797,7 +2028,9 @@ export const sessionHistoryItems = pgTable(
     sessionId: uuid("session_id")
       .notNull()
       .references(() => sessions.id, { onDelete: "cascade" }),
-    turnId: uuid("turn_id").references(() => sessionTurns.id, { onDelete: "set null" }),
+    turnId: uuid("turn_id").references(() => sessionTurns.id, {
+      onDelete: "set null",
+    }),
     // Numeric (not integer) so the synthetic compaction-summary row can be
     // inserted at a FRACTIONAL position (boundaryPosition - 0.5) that sorts ahead
     // of the kept tail without colliding with — and thus overwriting — the real
@@ -2061,7 +2294,9 @@ export const sessionRecordings = pgTable(
     sessionId: uuid("session_id")
       .notNull()
       .references(() => sessions.id, { onDelete: "cascade" }),
-    turnId: uuid("turn_id").references(() => sessionTurns.id, { onDelete: "set null" }),
+    turnId: uuid("turn_id").references(() => sessionTurns.id, {
+      onDelete: "set null",
+    }),
 
     state: text("state", { enum: sessionRecordingStateValues }).notNull(),
     mode: text("mode", { enum: sessionRecordingModeValues }).notNull(),
@@ -2088,7 +2323,7 @@ export const sessionRecordings = pgTable(
   }),
 );
 
-// Workbench v2 turn-end workspace capture (dossier §10.2; model: sessionRecordings).
+// Workbench v2 turn-end workspace capture (model: sessionRecordings).
 // One row per capture revision — a point-in-time snapshot of a session's changed
 // files, probed off the live box at turn end. The manifest (tree index + per-repo
 // status/diff + file index) and each after-image blob live in @opengeni/storage;
@@ -2111,7 +2346,9 @@ export const workspaceCaptures = pgTable(
     sessionId: uuid("session_id")
       .notNull()
       .references(() => sessions.id, { onDelete: "cascade" }),
-    turnId: uuid("turn_id").references(() => sessionTurns.id, { onDelete: "set null" }),
+    turnId: uuid("turn_id").references(() => sessionTurns.id, {
+      onDelete: "set null",
+    }),
 
     revision: bigint("revision", { mode: "number" }).notNull(),
     leaseEpoch: integer("lease_epoch").notNull(),
@@ -2147,8 +2384,8 @@ export const workspaceCaptures = pgTable(
   }),
 );
 
-// Channel-A interactive PTY sessions (P4.4 / modules/08-channel-a.md §3.1). The
-// ONLY new persistent state Channel A needs — FS/Git reads are stateless point
+// Interactive PTY sessions. This is the persistent state needed for a live
+// terminal; file and Git reads remain stateless point
 // queries; an interactive PTY is a live in-box process keyed by the SDK's numeric
 // exec-session id (writeStdin({sessionId})). We map our UUID ptyId <-> that id,
 // the owning workspace/session, the lease_epoch that fences it to the box it was
@@ -2193,7 +2430,7 @@ export const sandboxPtySessions = pgTable(
 
 // ============================================================================
 // Bring-your-own-compute (M2): first-class swappable sandboxes + enrollment +
-// metrics (migration 0024 / dossier §10.3 + §10.7 + §23). The session→box
+// metrics (migration 0024). The session→box
 // binding becomes a per-session mutable, epoch-fenced active_sandbox_id pointer
 // (declared on sessions above) that the routing proxy resolves PER TOOL CALL.
 
@@ -2267,7 +2504,7 @@ export const enrollments = pgTable(
 );
 
 // The OAuth 2.0 device-authorization (RFC 8628) PENDING request (M5, migration
-// 0025 / dossier §10.2 enrollment + §18 LOUD consent). An agent's `enroll` starts
+// 0025 / enrollment + §18 LOUD consent). An agent's `enroll` starts
 // a flow (POST /enrollments/device/start) → one short-TTL, single-use row keyed by
 // an opaque `device_code` (the agent polls with) + a short `user_code` (the user
 // types at the approve page). The user (workspace-membership / workspace:admin
@@ -2308,7 +2545,9 @@ export const deviceEnrollmentRequests = pgTable(
     machineName: text("machine_name"),
     // The exposure the agent REQUESTED (whole-machine in v1; loudly consented at
     // approve). Mirrors the enrollment column domain.
-    requestedExposure: text("requested_exposure", { enum: enrollmentExposureValues })
+    requestedExposure: text("requested_exposure", {
+      enum: enrollmentExposureValues,
+    })
       .notNull()
       .default("whole-machine"),
     // The agent CAN offer a display (a real screen / Xvfb is available) — gates
@@ -2328,8 +2567,12 @@ export const deviceEnrollmentRequests = pgTable(
     approvedAt: timestamp("approved_at", { withTimezone: true }),
     // The enrollment + sandbox the approve produced (acceptance #2: an enrollment
     // row AND a sandbox row appear). Null until approved.
-    enrollmentId: uuid("enrollment_id").references(() => enrollments.id, { onDelete: "set null" }),
-    sandboxId: uuid("sandbox_id").references(() => sandboxes.id, { onDelete: "set null" }),
+    enrollmentId: uuid("enrollment_id").references(() => enrollments.id, {
+      onDelete: "set null",
+    }),
+    sandboxId: uuid("sandbox_id").references(() => sandboxes.id, {
+      onDelete: "set null",
+    }),
     // The short-TTL expiry; a pending row past this is EXPIRED on poll.
     expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
@@ -2370,7 +2613,9 @@ export const sandboxes = pgTable(
       .references(() => workspaces.id, { onDelete: "cascade" }),
     kind: text("kind", { enum: sandboxKindValues }).notNull(),
     name: text("name").notNull(),
-    enrollmentId: uuid("enrollment_id").references(() => enrollments.id, { onDelete: "set null" }),
+    enrollmentId: uuid("enrollment_id").references(() => enrollments.id, {
+      onDelete: "set null",
+    }),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
   },
@@ -2521,7 +2766,9 @@ export const scheduledTaskRuns = pgTable(
     triggerType: text("trigger_type").notNull(),
     scheduledAt: timestamp("scheduled_at", { withTimezone: true }),
     firedAt: timestamp("fired_at", { withTimezone: true }).notNull().defaultNow(),
-    sessionId: uuid("session_id").references(() => sessions.id, { onDelete: "set null" }),
+    sessionId: uuid("session_id").references(() => sessions.id, {
+      onDelete: "set null",
+    }),
     triggerEventId: uuid("trigger_event_id"),
     // Stable Temporal producer identity. Activity replay/re-dispatch returns
     // the exact run instead of allocating a second schedule source row.
@@ -2559,6 +2806,8 @@ export const githubInstallations = pgTable(
     installationId: integer("installation_id").notNull(),
     accountLogin: text("account_login"),
     accountType: text("account_type"),
+    repositoryScope: text("repository_scope").notNull().default("all"),
+    linkedBySubjectId: text("linked_by_subject_id"),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
   },
@@ -2569,6 +2818,47 @@ export const githubInstallations = pgTable(
     ),
     installation: index("github_installations_installation_idx").on(table.installationId),
     workspace: index("github_installations_workspace_idx").on(table.workspaceId),
+    repositoryScopeCheck: check(
+      "github_installations_repository_scope_check",
+      sql`${table.repositoryScope} in ('all', 'selected')`,
+    ),
+  }),
+);
+
+export const githubInstallationRepositories = pgTable(
+  "github_installation_repositories",
+  {
+    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" }),
+    installationId: integer("installation_id").notNull(),
+    repositoryId: bigint("repository_id", { mode: "number" }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    installationRepository: uniqueIndex("github_install_repo_workspace_installation_repo_idx").on(
+      table.workspaceId,
+      table.installationId,
+      table.repositoryId,
+    ),
+    workspaceInstallation: index("github_install_repo_workspace_installation_idx").on(
+      table.workspaceId,
+      table.installationId,
+    ),
+    workspaceAccount: foreignKey({
+      columns: [table.workspaceId, table.accountId],
+      foreignColumns: [workspaces.id, workspaces.accountId],
+      name: "github_installation_repositories_workspace_account_fk",
+    }).onDelete("cascade"),
+    installationBinding: foreignKey({
+      columns: [table.workspaceId, table.installationId],
+      foreignColumns: [githubInstallations.workspaceId, githubInstallations.installationId],
+      name: "github_installation_repositories_installation_fk",
+    }).onDelete("cascade"),
   }),
 );
 
@@ -2588,10 +2878,26 @@ export const usageEvents = pgTable(
     unit: text("unit").notNull(),
     sourceResourceType: text("source_resource_type"),
     sourceResourceId: text("source_resource_id"),
+    // Exact execution source for host usage export. These are deliberately
+    // validated soft references rather than cascading foreign keys: usage is
+    // an immutable billing/audit fact and must retain its source identity after
+    // a session or turn is deleted.
+    sessionId: uuid("session_id"),
+    turnId: uuid("turn_id"),
+    turnAttemptId: uuid("turn_attempt_id"),
+    initiatorKind: text("initiator_kind"),
+    initiatorSubjectId: text("initiator_subject_id"),
+    initiatorContext: jsonb("initiator_context")
+      .$type<Record<string, unknown>>()
+      .notNull()
+      .default({}),
+    origin: text("origin"),
     idempotencyKey: text("idempotency_key").notNull(),
     occurredAt: timestamp("occurred_at", { withTimezone: true }).notNull(),
     recordedAt: timestamp("recorded_at", { withTimezone: true }).notNull().defaultNow(),
-    exportedToBillingAt: timestamp("exported_to_billing_at", { withTimezone: true }),
+    exportedToBillingAt: timestamp("exported_to_billing_at", {
+      withTimezone: true,
+    }),
     billingProviderEventId: text("billing_provider_event_id"),
   },
   (table) => ({
@@ -2606,6 +2912,208 @@ export const usageEvents = pgTable(
       table.eventType,
       table.occurredAt,
     ),
+    workspaceSession: index("usage_events_workspace_session_idx").on(
+      table.workspaceId,
+      table.sessionId,
+      table.occurredAt,
+    ),
+    contextHierarchy: check(
+      "usage_events_context_hierarchy_check",
+      sql`(${table.turnId} is null or ${table.sessionId} is not null)
+        and (${table.turnAttemptId} is null or ${table.turnId} is not null)`,
+    ),
+    initiatorConsistent: check(
+      "usage_events_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)`,
+    ),
+    attributionContextBytes: check(
+      "usage_events_initiator_context_bytes_check",
+      sql`octet_length(${table.initiatorContext}::text) <= 4096`,
+    ),
+    originValid: check(
+      "usage_events_origin_check",
+      sql`${table.origin} is null or ${table.origin} in (
+        'user', 'scheduled_task', 'api', 'goal', 'system', 'compaction'
+      )`,
+    ),
+  }),
+);
+
+/** Singleton, migration-installed gate. Standalone defaults keep both off. */
+export const hostExportConfig = pgTable(
+  "host_export_config",
+  {
+    id: integer("id").primaryKey().default(1),
+    sessionEventsEnabled: boolean("session_events_enabled").notNull().default(false),
+    usageEventsEnabled: boolean("usage_events_enabled").notNull().default(false),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    singleton: check("host_export_config_singleton_check", sql`${table.id} = 1`),
+  }),
+);
+
+/**
+ * Transactional delivery buffer. It intentionally has no tenant/source FKs:
+ * a workspace deletion must not erase an already-committed, unacknowledged
+ * host fact. Payloads are sanitized/bounded before they reach this table.
+ */
+export const hostExportOutbox = pgTable(
+  "host_export_outbox",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    exportKind: text("export_kind").notNull(),
+    exportCursor: bigint("export_cursor", { mode: "bigint" }),
+    sourceId: uuid("source_id").notNull(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    sessionId: uuid("session_id"),
+    rootSessionId: uuid("root_session_id"),
+    turnId: uuid("turn_id"),
+    turnGeneration: integer("turn_generation"),
+    turnAttemptId: uuid("turn_attempt_id"),
+    sessionSequence: integer("session_sequence"),
+    clientEventId: text("client_event_id"),
+    turnAssociation: text("turn_association"),
+    duplicateOfEventId: uuid("duplicate_of_event_id"),
+    duplicateReason: text("duplicate_reason"),
+    eventType: text("event_type").notNull(),
+    idempotencyKey: text("idempotency_key").notNull(),
+    initiator: jsonb("initiator").$type<Record<string, unknown> | null>(),
+    initiatorContext: jsonb("initiator_context")
+      .$type<Record<string, unknown>>()
+      .notNull()
+      .default({}),
+    origin: text("origin"),
+    payload: jsonb("payload").$type<unknown>().notNull(),
+    envelopeBytes: integer("envelope_bytes").notNull(),
+    occurredAt: timestamp("occurred_at", { withTimezone: true }).notNull(),
+    sourceRecordedAt: timestamp("source_recorded_at", { withTimezone: true }).notNull(),
+    enqueuedAt: timestamp("enqueued_at", { withTimezone: true }).notNull(),
+  },
+  (table) => ({
+    kindValid: check(
+      "host_export_outbox_kind_check",
+      sql`${table.exportKind} in ('session_event', 'usage_event')`,
+    ),
+    sourceUnique: uniqueIndex("host_export_outbox_source_uq").on(table.exportKind, table.sourceId),
+    cursorUnique: uniqueIndex("host_export_outbox_cursor_uq")
+      .on(table.exportKind, table.exportCursor)
+      .where(sql`${table.exportCursor} is not null`),
+    unassigned: index("host_export_outbox_unassigned_idx")
+      .on(table.exportKind, table.enqueuedAt, table.id)
+      .where(sql`${table.exportCursor} is null`),
+    unassignedSession: index("host_export_outbox_unassigned_session_idx")
+      .on(table.exportKind, table.sessionId, table.sessionSequence)
+      .where(sql`${table.exportCursor} is null and ${table.sessionId} is not null`),
+    contextBytes: check(
+      "host_export_outbox_context_bytes_check",
+      sql`octet_length(${table.initiatorContext}::text) <= 4096`,
+    ),
+    originValid: check(
+      "host_export_outbox_origin_check",
+      sql`${table.origin} is null or ${table.origin} in (
+        'user', 'scheduled_task', 'api', 'goal', 'system', 'compaction'
+      )`,
+    ),
+  }),
+);
+
+export const hostExportCursorState = pgTable(
+  "host_export_cursor_state",
+  {
+    exportKind: text("export_kind").primaryKey(),
+    nextCursor: bigint("next_cursor", { mode: "bigint" }).notNull().default(1n),
+    prunedThrough: bigint("pruned_through", { mode: "bigint" }).notNull().default(0n),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    kindValid: check(
+      "host_export_cursor_state_kind_check",
+      sql`${table.exportKind} in ('session_event', 'usage_event')`,
+    ),
+    cursorValid: check(
+      "host_export_cursor_state_next_check",
+      sql`${table.nextCursor} > 0 and ${table.prunedThrough} >= 0
+        and ${table.prunedThrough} < ${table.nextCursor}`,
+    ),
+  }),
+);
+
+/** Named at-least-once consumer checkpoint and one-batch lease. */
+export const hostExportConsumers = pgTable(
+  "host_export_consumers",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    consumerId: text("consumer_id").notNull(),
+    exportKind: text("export_kind").notNull(),
+    checkpoint: bigint("checkpoint", { mode: "bigint" }).notNull().default(0n),
+    enabled: boolean("enabled").notNull().default(true),
+    leaseToken: uuid("lease_token"),
+    leaseHolderId: text("lease_holder_id"),
+    leaseExpiresAt: timestamp("lease_expires_at", { withTimezone: true }),
+    leaseFrom: bigint("lease_from", { mode: "bigint" }),
+    leaseThrough: bigint("lease_through", { mode: "bigint" }),
+    consecutiveFailures: integer("consecutive_failures").notNull().default(0),
+    nextAttemptAt: timestamp("next_attempt_at", { withTimezone: true }).notNull().defaultNow(),
+    lastError: text("last_error"),
+    lastErrorAt: timestamp("last_error_at", { withTimezone: true }),
+    blockedAt: timestamp("blocked_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    consumerKind: uniqueIndex("host_export_consumers_kind_id_uq").on(
+      table.exportKind,
+      table.consumerId,
+    ),
+    kindValid: check(
+      "host_export_consumers_kind_check",
+      sql`${table.exportKind} in ('session_event', 'usage_event')`,
+    ),
+    checkpointValid: check("host_export_consumers_checkpoint_check", sql`${table.checkpoint} >= 0`),
+    due: index("host_export_consumers_due_idx").on(
+      table.enabled,
+      table.blockedAt,
+      table.nextAttemptAt,
+    ),
+  }),
+);
+
+/** Explicit poison-row disposition; transient failures never write here. */
+export const hostExportDeadLetters = pgTable(
+  "host_export_dead_letters",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    consumerId: text("consumer_id").notNull(),
+    exportKind: text("export_kind").notNull(),
+    exportCursor: bigint("export_cursor", { mode: "bigint" }).notNull(),
+    sourceId: uuid("source_id").notNull(),
+    reason: text("reason").notNull(),
+    envelope: jsonb("envelope").$type<Record<string, unknown>>().notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    consumerCursor: uniqueIndex("host_export_dead_letters_consumer_cursor_uq").on(
+      table.exportKind,
+      table.consumerId,
+      table.exportCursor,
+    ),
+    kindValid: check(
+      "host_export_dead_letters_kind_check",
+      sql`${table.exportKind} in ('session_event', 'usage_event')`,
+    ),
+    reasonValid: check(
+      "host_export_dead_letters_reason_check",
+      sql`length(${table.reason}) between 1 and 500`,
+    ),
+    envelopeBytes: check(
+      "host_export_dead_letters_envelope_bytes_check",
+      sql`pg_column_size(${table.envelope}) <= 114688`,
+    ),
   }),
 );
 
@@ -2616,7 +3124,9 @@ export const creditLedgerEntries = pgTable(
     accountId: uuid("account_id")
       .notNull()
       .references(() => managedAccounts.id, { onDelete: "cascade" }),
-    workspaceId: uuid("workspace_id").references(() => workspaces.id, { onDelete: "set null" }),
+    workspaceId: uuid("workspace_id").references(() => workspaces.id, {
+      onDelete: "set null",
+    }),
     type: text("type").notNull(),
     amountMicros: bigint("amount_micros", { mode: "number" }).notNull(),
     currency: text("currency").notNull().default("usd"),
@@ -2674,8 +3184,12 @@ export const auditEvents = pgTable(
   "audit_events",
   {
     id: uuid("id").primaryKey().defaultRandom(),
-    accountId: uuid("account_id").references(() => managedAccounts.id, { onDelete: "set null" }),
-    workspaceId: uuid("workspace_id").references(() => workspaces.id, { onDelete: "set null" }),
+    accountId: uuid("account_id").references(() => managedAccounts.id, {
+      onDelete: "set null",
+    }),
+    workspaceId: uuid("workspace_id").references(() => workspaces.id, {
+      onDelete: "set null",
+    }),
     subjectId: text("subject_id"),
     action: text("action").notNull(),
     targetType: text("target_type"),
@@ -2770,8 +3284,12 @@ export const capabilityCatalogItems = pgTable(
   "capability_catalog_items",
   {
     id: text("id").notNull(),
-    accountId: uuid("account_id").references(() => managedAccounts.id, { onDelete: "cascade" }),
-    workspaceId: uuid("workspace_id").references(() => workspaces.id, { onDelete: "cascade" }),
+    accountId: uuid("account_id").references(() => managedAccounts.id, {
+      onDelete: "cascade",
+    }),
+    workspaceId: uuid("workspace_id").references(() => workspaces.id, {
+      onDelete: "cascade",
+    }),
     kind: text("kind").notNull(),
     source: text("source").notNull().default("manual"),
     name: text("name").notNull(),