@opengeni/db 1.0.1 → 3.1.0-canary.0

package/src/browser-sessions.ts

@@ -23,6 +23,7 @@ import {
   type NetworkRouteConsistency as NetworkRouteConsistencyValue,
 } from "@opengeni/contracts";
 import { and, desc, eq, inArray, isNull, sql } from "drizzle-orm";
+import { attachedDeviceGenerationMatches } from "./attached-browser-devices";
 import { type Database, withRlsContext } from "./database";
 import {
   advanceWorkspaceInteractionRevision,
@@ -2194,6 +2195,15 @@ export async function touchBrowserSessionController(
           )
           .limit(1);
         if (!observed) return false;
+        if (observed.placementKind === "attached_device") {
+          if (!observed.deviceId || !observed.placementInstanceId) return false;
+          const current = await attachedDeviceGenerationMatches(tx, {
+            workspaceId: input.workspaceId,
+            deviceId: observed.deviceId,
+            placementInstanceId: observed.placementInstanceId,
+          });
+          if (!current) return false;
+        }
         if (observed.controllerHostSandboxGroupId) {
           // Match the reaper's exact lease -> holder -> BrowserSession lock
           // order. The pre-lock observation is only a locator; every authority

package/src/capability-integrations.ts

@@ -15,6 +15,7 @@ import {
   withWorkspaceSubjectRls,
   type Database,
 } from "./database";
+import { connectionScopeKey } from "./connection-scopes";
 import {
   ensureIntegrationFacetDefinition,
   integrationBindingKey,
@@ -639,6 +640,176 @@ export async function listInstalledApiIntegrations(
       );
 }
 
+type ApiIntegrationServerAuthorityMetadata = {
+  serverId: string;
+  connectionId: string | null;
+  providerDomain: string;
+  connectionKind: string | null;
+  subjectScope: "workspace" | "subject";
+};
+
+async function listInstalledApiIntegrationServerAuthorityMetadataInRlsContext(
+  scopedDb: Database,
+  workspaceId: string,
+  subjectId?: string,
+): Promise<ApiIntegrationServerAuthorityMetadata[]> {
+  const rows = await scopedDb
+    .select({
+      serverId: schema.integrationFacetBindings.runtimeKey,
+      connectionId: schema.integrationFacetBindings.connectionId,
+      providerDomain: schema.capabilityIntegrationFacets.providerDomain,
+      connectionKind: sql<
+        string | null
+      >`${schema.integrationFacetBindings.config} ->> 'connectionKind'`,
+      subjectScope: sql<
+        string | null
+      >`${schema.integrationFacetBindings.config} ->> 'subjectScope'`,
+    })
+    .from(schema.integrationFacetBindings)
+    .innerJoin(
+      schema.integrationFacetDefinitions,
+      eq(schema.integrationFacetDefinitions.id, schema.integrationFacetBindings.facetDefinitionId),
+    )
+    .innerJoin(
+      schema.capabilityIntegrationFacets,
+      eq(
+        schema.capabilityIntegrationFacets.facetId,
+        schema.integrationFacetDefinitions.integrationFacetId,
+      ),
+    )
+    .innerJoin(
+      schema.capabilityFacetInstallations,
+      eq(
+        schema.capabilityFacetInstallations.id,
+        schema.integrationFacetBindings.integrationFacetInstallationId,
+      ),
+    )
+    .innerJoin(
+      schema.capabilityPluginInstallations,
+      eq(
+        schema.capabilityPluginInstallations.id,
+        schema.capabilityFacetInstallations.pluginInstallationId,
+      ),
+    )
+    .innerJoin(
+      schema.capabilityApiFacets,
+      eq(schema.capabilityApiFacets.integrationFacetId, schema.capabilityIntegrationFacets.facetId),
+    )
+    .where(
+      and(
+        eq(schema.capabilityPluginInstallations.workspaceId, workspaceId),
+        eq(schema.capabilityPluginInstallations.status, "active"),
+        eq(schema.capabilityFacetInstallations.status, "active"),
+        eq(schema.integrationFacetDefinitions.kind, "tools"),
+        eq(schema.integrationFacetBindings.status, "active"),
+        sql`${schema.integrationFacetBindings.runtimeKey} is not null`,
+        sql`exists (
+          select 1 from ${schema.capabilityComponentOwners} owner
+          where owner.facet_installation_id = ${schema.capabilityFacetInstallations.id}
+            and ${effectiveCapabilityOwnerSql(sql`owner.owner_kind`, sql`owner.owner_id`)}
+        )`,
+        sql`exists (
+          select 1 from ${schema.integrationFacetBindingOwners} owner
+          where owner.binding_id = ${schema.integrationFacetBindings.id}
+            and ${effectiveCapabilityOwnerSql(sql`owner.owner_kind`, sql`owner.owner_id`)}
+        )`,
+        sql`exists (
+          select 1 from ${schema.capabilityFacetInstallations} api_installation
+          where api_installation.plugin_installation_id = ${schema.capabilityPluginInstallations.id}
+            and api_installation.facet_id = ${schema.capabilityApiFacets.facetId}
+            and api_installation.status = 'active'
+        )`,
+        subjectId
+          ? sql`(
+              ${schema.integrationFacetBindings.connectionId} is null
+              or exists (
+                select 1 from ${schema.connections} connection
+                where connection.id = ${schema.integrationFacetBindings.connectionId}
+                  and (connection.subject_id is null or connection.subject_id = ${subjectId})
+              )
+            )`
+          : sql`(
+              ${schema.integrationFacetBindings.connectionId} is null
+              or exists (
+                select 1 from ${schema.connections} connection
+                where connection.id = ${schema.integrationFacetBindings.connectionId}
+                  and connection.subject_id is null
+              )
+            )`,
+      ),
+    );
+  return rows.flatMap((row) =>
+    row.serverId
+      ? [
+          {
+            serverId: row.serverId,
+            connectionId: row.connectionId,
+            providerDomain: row.providerDomain,
+            connectionKind: row.connectionKind,
+            subjectScope: row.subjectScope === "subject" ? "subject" : "workspace",
+          },
+        ]
+      : [],
+  );
+}
+
+/**
+ * Exact runnable API-integration server ids for a scheduled service run.
+ * Only runtime ids and the minimum delegation-matching metadata are selected;
+ * no integration definition, credential, token, endpoint, or tool schema is
+ * materialized before incident admission.
+ */
+export async function listInstalledApiIntegrationServerIdsForDelegations(
+  db: Database,
+  workspaceId: string,
+  delegations: readonly {
+    serverId: string;
+    connectionId: string;
+    providerDomain: string;
+    ownerSubjectId: string;
+    kind?: string | undefined;
+  }[],
+): Promise<string[]> {
+  const workspace = await withWorkspaceRls(
+    db,
+    workspaceId,
+    async (scopedDb) =>
+      await listInstalledApiIntegrationServerAuthorityMetadataInRlsContext(scopedDb, workspaceId),
+  );
+  const byServerId = new Set(workspace.map((entry) => entry.serverId));
+  const owners = [...new Set(delegations.map((delegation) => delegation.ownerSubjectId))];
+  for (const ownerSubjectId of owners) {
+    const ownerEntries = await withWorkspaceSubjectRls(
+      db,
+      workspaceId,
+      ownerSubjectId,
+      async (scopedDb) =>
+        await listInstalledApiIntegrationServerAuthorityMetadataInRlsContext(
+          scopedDb,
+          workspaceId,
+          ownerSubjectId,
+        ),
+    );
+    const exact = delegations.filter((delegation) => delegation.ownerSubjectId === ownerSubjectId);
+    for (const entry of ownerEntries) {
+      if (
+        entry.subjectScope === "subject" &&
+        entry.connectionId &&
+        exact.some(
+          (delegation) =>
+            delegation.serverId === entry.serverId &&
+            delegation.connectionId === entry.connectionId &&
+            delegation.providerDomain.toLowerCase() === entry.providerDomain.toLowerCase() &&
+            (delegation.kind ?? "") === (entry.connectionKind ?? ""),
+        )
+      ) {
+        byServerId.add(entry.serverId);
+      }
+    }
+  }
+  return [...byServerId];
+}
+
 /**
  * Read installed API Integrations from a transaction that already carries the
  * workspace RLS context. This is intentionally separate from the public
@@ -1180,8 +1351,11 @@ async function loadInstallConnection(
     throw new Error("API Integration connection provider does not match the destination");
   }
   assertConnectionKindMatchesAuth(input.authScheme, connection.kind);
+  const grantedScopes = new Set(
+    connection.grantedScopes.map((scope) => connectionScopeKey(connection.providerDomain, scope)),
+  );
   const missing = normalizedStrings(input.requiredScopes ?? [], 256).filter(
-    (scope) => !connection.grantedScopes.includes(scope),
+    (scope) => !grantedScopes.has(connectionScopeKey(connection.providerDomain, scope)),
   );
   if (missing.length > 0) {
     throw new Error("API Integration connection is missing required scopes");

package/src/child-lifecycle-notices.ts

@@ -0,0 +1,241 @@
+import {
+  CHILD_PAUSED_REASON_MAX_BYTES,
+  CHILD_PROGRESS_NOTE_MAX_BYTES,
+  CHILD_REQUIRES_ACTION_MAX_REQUESTS,
+  CHILD_REQUIRES_ACTION_PAYLOAD_MAX_BYTES,
+  CHILD_REQUIRES_ACTION_QUESTION_PREVIEW_MAX_BYTES,
+  approvalIdentifier,
+  type ChildPausedPayload,
+  type ChildProgressPayload,
+  type ChildRequiresActionPayload,
+  type ChildRequiresActionRequest,
+  type ChildRequiresActionResolvedPayload,
+  type ChildWaitingCapacityPayload,
+  type HumanInputQuestion,
+} from "@opengeni/contracts";
+
+/**
+ * Child lifecycle notices (`child_requires_action`,
+ * `child_requires_action_resolved`, `child_paused`, `child_waiting_capacity`,
+ * `child_progress`) are produced only while this process-global flag is on.
+ * The deployment value is `OPENGENI_CHILD_LIFECYCLE_NOTICES_ENABLED`, parsed
+ * once at boot by `@opengeni/config` (`settings.childLifecycleNoticesEnabled`)
+ * and installed here by the API app and both worker roles. Rolling hazard: a
+ * worker from before these kinds existed throws in `mapSessionSystemUpdate`
+ * on an unknown kind, so the flag stays off until the whole fleet runs a new
+ * image. Delivery and consumption of an already committed notice never read
+ * the flag; only production does.
+ */
+let childLifecycleNoticesEnabledFlag = false;
+
+export function configureChildLifecycleNotices(input: { enabled: boolean }): void {
+  childLifecycleNoticesEnabledFlag = input.enabled === true;
+}
+
+export function childLifecycleNoticesEnabled(): boolean {
+  return childLifecycleNoticesEnabledFlag;
+}
+
+/** Bounded UTF-8 prefix with an explicit marker; never splits a code point. */
+export function boundedChildNoticeText(
+  value: string,
+  maxBytes: number,
+): { text: string; truncated: boolean } {
+  const encoder = new TextEncoder();
+  const bytes = encoder.encode(value);
+  if (bytes.byteLength <= maxBytes) return { text: value, truncated: false };
+  const marker = "…";
+  const budget = Math.max(0, maxBytes - encoder.encode(marker).byteLength);
+  let end = Math.min(budget, bytes.byteLength);
+  while (end > 0 && end < bytes.byteLength && (bytes[end]! & 0xc0) === 0x80) end -= 1;
+  return { text: `${new TextDecoder().decode(bytes.subarray(0, end))}${marker}`, truncated: true };
+}
+
+export const CHILD_LIFECYCLE_DEDUPE_PREFIX = {
+  requiresAction: "child-requires-action",
+  requiresActionResolved: "child-requires-action-resolved",
+  paused: "child-paused",
+  waitingCapacity: "child-waiting-capacity",
+  progress: "child-progress",
+} as const;
+
+export function childRequiresActionDedupeKey(input: {
+  childSessionId: string;
+  turnId: string;
+  turnGeneration: number;
+}): string {
+  return `${CHILD_LIFECYCLE_DEDUPE_PREFIX.requiresAction}:${input.childSessionId}:${input.turnId}:${input.turnGeneration}`;
+}
+
+export function childRequiresActionResolvedDedupeKey(input: {
+  childSessionId: string;
+  turnId: string;
+  turnGeneration: number;
+  requestId: string | null;
+  approvalId: string | null;
+}): string {
+  return `${CHILD_LIFECYCLE_DEDUPE_PREFIX.requiresActionResolved}:${input.childSessionId}:${input.turnId}:${input.turnGeneration}:${input.requestId ?? input.approvalId ?? "unknown"}`;
+}
+
+export function childPausedDedupeKey(input: { childSessionId: string; receiptId: string }): string {
+  return `${CHILD_LIFECYCLE_DEDUPE_PREFIX.paused}:${input.childSessionId}:${input.receiptId}`;
+}
+
+export function childWaitingCapacityDedupeKey(input: {
+  childSessionId: string;
+  waiterId: string;
+}): string {
+  return `${CHILD_LIFECYCLE_DEDUPE_PREFIX.waitingCapacity}:${input.childSessionId}:${input.waiterId}`;
+}
+
+export function childProgressDedupeKey(input: {
+  childSessionId: string;
+  receiptId: string;
+}): string {
+  return `${CHILD_LIFECYCLE_DEDUPE_PREFIX.progress}:${input.childSessionId}:${input.receiptId}`;
+}
+
+/** Bounded, secret-free tool name of a serialized SDK approval interruption. */
+function approvalToolName(value: unknown): string | null {
+  if (!value || typeof value !== "object") return null;
+  const approval = value as Record<string, unknown>;
+  const rawItem =
+    approval.rawItem && typeof approval.rawItem === "object"
+      ? (approval.rawItem as Record<string, unknown>)
+      : null;
+  const candidate = rawItem?.name ?? approval.name;
+  return typeof candidate === "string" && candidate.length > 0
+    ? boundedChildNoticeText(candidate, 128).text
+    : null;
+}
+
+/**
+ * Build the bounded child_requires_action payload from the child's frozen
+ * human-input requests and pending approvals. Only typed, content-free facts
+ * plus one bounded first-question preview per request cross to the parent:
+ * never subject ids, credentials, or raw tool arguments. The whole payload
+ * stays within CHILD_REQUIRES_ACTION_PAYLOAD_MAX_BYTES by dropping trailing
+ * requests and recording `truncated`.
+ */
+export function buildChildRequiresActionPayload(input: {
+  childSessionId: string;
+  childTurnId: string;
+  childTurnGeneration: number;
+  humanInputRequests: ReadonlyArray<{
+    id: string;
+    questions: readonly HumanInputQuestion[];
+    allowSkip: boolean;
+    expiresAt?: Date | null;
+  }>;
+  pendingApprovals: readonly unknown[];
+}): ChildRequiresActionPayload {
+  const requests: ChildRequiresActionRequest[] = [];
+  for (const request of input.humanInputRequests) {
+    const first = request.questions[0];
+    requests.push({
+      kind: "human_input",
+      requestId: request.id,
+      questionCount: request.questions.length,
+      firstQuestion: boundedChildNoticeText(
+        typeof first?.prompt === "string" ? first.prompt : "",
+        CHILD_REQUIRES_ACTION_QUESTION_PREVIEW_MAX_BYTES,
+      ).text,
+      allowSkip: request.allowSkip,
+      expiresAt: request.expiresAt ? request.expiresAt.toISOString() : null,
+    });
+  }
+  const seenApprovals = new Set<string>();
+  for (const pending of input.pendingApprovals) {
+    const approvalId = approvalIdentifier(pending);
+    if (!approvalId || seenApprovals.has(approvalId)) continue;
+    seenApprovals.add(approvalId);
+    requests.push({
+      kind: "approval",
+      approvalId: boundedChildNoticeText(approvalId, 256).text,
+      toolName: approvalToolName(pending),
+    });
+  }
+  let truncated = requests.length > CHILD_REQUIRES_ACTION_MAX_REQUESTS;
+  let bounded = requests.slice(0, CHILD_REQUIRES_ACTION_MAX_REQUESTS);
+  const build = (): ChildRequiresActionPayload => ({
+    type: "child_requires_action",
+    childSessionId: input.childSessionId,
+    childTurnId: input.childTurnId,
+    childTurnGeneration: input.childTurnGeneration,
+    requests: bounded,
+    truncated,
+  });
+  let payload = build();
+  while (
+    bounded.length > 0 &&
+    Buffer.byteLength(JSON.stringify(payload)) > CHILD_REQUIRES_ACTION_PAYLOAD_MAX_BYTES
+  ) {
+    bounded = bounded.slice(0, -1);
+    truncated = true;
+    payload = build();
+  }
+  return payload;
+}
+
+export function childRequiresActionSummary(
+  childSessionId: string,
+  payload: ChildRequiresActionPayload,
+): string {
+  const humanInputs = payload.requests.filter((request) => request.kind === "human_input");
+  const approvals = payload.requests.filter((request) => request.kind === "approval");
+  const first = humanInputs[0];
+  const lines = [
+    `Worker ${childSessionId} is blocked and needs input (turn ${payload.childTurnId}).`,
+  ];
+  if (first && first.kind === "human_input") {
+    lines.push(
+      `It asked: ${first.firstQuestion}${first.questionCount > 1 ? ` (+${first.questionCount - 1} more question${first.questionCount > 2 ? "s" : ""})` : ""}${humanInputs.length > 1 ? ` [${humanInputs.length} open requests]` : ""}.`,
+    );
+  }
+  if (approvals.length > 0) {
+    const names = approvals
+      .map((request) => (request.kind === "approval" ? request.toolName : null))
+      .filter((name): name is string => name !== null);
+    lines.push(
+      `${approvals.length} tool approval${approvals.length > 1 ? "s are" : " is"} waiting for a human${names.length > 0 ? ` (${names.join(", ")})` : ""}.`,
+    );
+  }
+  if (payload.truncated) lines.push("The request list was truncated.");
+  return lines.join(" ");
+}
+
+export function childRequiresActionResolvedSummary(
+  childSessionId: string,
+  payload: ChildRequiresActionResolvedPayload,
+): string {
+  const subject = payload.requestId ? "input request" : "approval";
+  return `Worker ${childSessionId}: its ${subject} was ${payload.outcome} (by ${payload.respondedByKind.replace("_", " ")}); the worker is no longer blocked on it.`;
+}
+
+export function childPausedSummary(childSessionId: string, payload: ChildPausedPayload): string {
+  const base = `Worker ${childSessionId} was paused by ${payload.actorKind === "agent" ? "an agent" : payload.actorKind === "api" ? "the API" : "a human"}.`;
+  return payload.reason ? `${base} Reason: ${payload.reason}` : base;
+}
+
+export function childWaitingCapacitySummary(
+  childSessionId: string,
+  payload: ChildWaitingCapacityPayload,
+): string {
+  return `Worker ${childSessionId} is waiting for ${payload.provider === "codex" ? "Codex" : "xAI"} provider capacity${payload.nextCheckAt ? ` (next check ${payload.nextCheckAt})` : ""}; its turn resumes automatically.`;
+}
+
+export function childProgressSummary(
+  childSessionId: string,
+  payload: ChildProgressPayload,
+): string {
+  return `Worker ${childSessionId} progress: ${payload.progressNote}`;
+}
+
+export function boundedChildPausedReason(reason: string | null | undefined): string | null {
+  if (reason === null || reason === undefined || reason.length === 0) return null;
+  return boundedChildNoticeText(reason, CHILD_PAUSED_REASON_MAX_BYTES).text;
+}
+
+export function boundedChildProgressNote(note: string): string {
+  return boundedChildNoticeText(note, CHILD_PROGRESS_NOTE_MAX_BYTES).text;
+}

package/src/codemode-operations.ts

@@ -55,15 +55,6 @@ export class CodemodeToolApprovalRequiredError extends Error {
   }
 }
 
-export class CodemodeCallBudgetExceededError extends Error {
-  readonly code = "codemode_call_budget_exhausted";
-
-  constructor() {
-    super("Codemode call budget is exhausted for this turn");
-    this.name = "CodemodeCallBudgetExceededError";
-  }
-}
-
 export class CodemodePayloadTooLargeError extends Error {
   readonly code = "codemode_payload_too_large";
 
@@ -81,13 +72,12 @@ export type SubmitCodemodeOperationInput = {
   attemptId: string;
   executionGeneration: number;
   call: AttemptToolCallValue;
-  callLimit: number;
 };
 
 /**
  * Bind one caller-provided operation id to one exact catalog call. Duplicate
  * submission of identical bytes is free and returns the same row; repurposing
- * the id fails. Admission, budget reservation and insert share one turn lock.
+ * the id fails. Admission and insert share one turn lock.
  */
 export async function submitCodemodeOperation(
   db: Database,
@@ -120,7 +110,6 @@ export async function submitCodemodeOperation(
             status: schema.sessionTurns.status,
             activeAttemptId: schema.sessionTurns.activeAttemptId,
             executionGeneration: schema.sessionTurns.executionGeneration,
-            callCount: schema.sessionTurns.codemodeCallCount,
           })
           .from(schema.sessionTurns)
           .where(
@@ -141,10 +130,6 @@ export async function submitCodemodeOperation(
         ) {
           throw new CodemodeOperationNotExecutableError();
         }
-        if (!Number.isInteger(input.callLimit) || input.callLimit < 1) {
-          throw new CodemodeCallBudgetExceededError();
-        }
-        if (turn.callCount >= input.callLimit) throw new CodemodeCallBudgetExceededError();
 
         const [catalogRow] = await tx
           .select({ catalog: schema.sessionAttemptToolCatalogs.catalog })
@@ -180,25 +165,6 @@ export async function submitCodemodeOperation(
           throw new CodemodeToolApprovalRequiredError();
         }
 
-        const [counter] = await tx
-          .update(schema.sessionTurns)
-          .set({
-            codemodeCallCount: sql`${schema.sessionTurns.codemodeCallCount} + 1`,
-            updatedAt: new Date(),
-          })
-          .where(
-            and(
-              eq(schema.sessionTurns.workspaceId, input.workspaceId),
-              eq(schema.sessionTurns.id, input.turnId),
-              eq(schema.sessionTurns.status, "running"),
-              eq(schema.sessionTurns.activeAttemptId, input.attemptId),
-              eq(schema.sessionTurns.executionGeneration, input.executionGeneration),
-              sql`${schema.sessionTurns.codemodeCallCount} < ${input.callLimit}`,
-            ),
-          )
-          .returning({ count: schema.sessionTurns.codemodeCallCount });
-        if (!counter) throw new CodemodeCallBudgetExceededError();
-
         const [created] = await tx
           .insert(schema.sessionAttemptCodemodeCalls)
           .values({

package/src/company-brain-context-selection-schema.ts

@@ -0,0 +1,100 @@
+import {
+  boolean,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+import type { CompanyBrainMemorySelectionReference } from "./company-brain-context-selection";
+
+/**
+ * Content-free accepted-logical-turn selection receipt. Migration 0259 owns
+ * the exact-attempt writer, immutable trigger, FORCE-RLS policy, and grants.
+ */
+export const companyBrainContextSelectionReceipts = pgTable(
+  "company_brain_context_selection_receipts",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    sessionId: uuid("session_id").notNull(),
+    rootSessionId: uuid("root_session_id").notNull(),
+    turnId: uuid("turn_id").notNull(),
+    createdByAttemptId: uuid("created_by_attempt_id").notNull(),
+    createdByExecutionGeneration: integer("created_by_execution_generation").notNull(),
+    acceptedAt: timestamp("accepted_at", { withTimezone: true }).notNull(),
+    sessionRole: text("session_role").notNull(),
+    memoryEnabled: boolean("memory_enabled").notNull(),
+    memoryPromptMode: text("memory_prompt_mode").notNull(),
+    companyProfileIncluded: boolean("company_profile_included").notNull(),
+    instructionPolicyEntryHash: text("instruction_policy_entry_hash").notNull(),
+    preferenceDescriptorHash: text("preference_descriptor_hash"),
+    companyProfileSnapshotHash: text("company_profile_snapshot_hash").notNull(),
+    turnContextSnapshotId: uuid("turn_context_snapshot_id").notNull(),
+    turnContextSnapshotHash: text("turn_context_snapshot_hash").notNull(),
+    turnContextSnapshotSource: text("turn_context_snapshot_source").notNull(),
+    memorySelections: jsonb("memory_selections")
+      .$type<readonly CompanyBrainMemorySelectionReference[]>()
+      .notNull(),
+    renderedMemorySelections: jsonb("rendered_memory_selections")
+      .$type<readonly CompanyBrainMemorySelectionReference[]>()
+      .notNull(),
+    selectionHash: text("selection_hash").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    logicalTurn: uniqueIndex("company_brain_context_selection_turn_uq").on(
+      table.workspaceId,
+      table.turnId,
+    ),
+    workspaceTimeline: index("company_brain_context_selection_workspace_time_idx").on(
+      table.workspaceId,
+      table.createdAt,
+      table.id,
+    ),
+  }),
+);
+
+/**
+ * Exact bounded accepted-turn authority that may contain the legacy workspace
+ * instruction fallback. It is deliberately separate from the content-free
+ * selection receipt and has no direct runtime table privileges.
+ */
+export const companyBrainTurnContextSnapshots = pgTable(
+  "company_brain_turn_context_snapshots",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    sessionId: uuid("session_id").notNull(),
+    rootSessionId: uuid("root_session_id").notNull(),
+    turnId: uuid("turn_id").notNull(),
+    acceptedAt: timestamp("accepted_at", { withTimezone: true }).notNull(),
+    memoryEnabled: boolean("memory_enabled").notNull(),
+    memoryPromptMode: text("memory_prompt_mode").notNull(),
+    legacyWorkspaceInstructions: text("legacy_workspace_instructions"),
+    legacyWorkspaceInstructionsOriginalUtf8Bytes: integer(
+      "legacy_workspace_instructions_original_utf8_bytes",
+    ),
+    legacyWorkspaceInstructionsTruncated: boolean(
+      "legacy_workspace_instructions_truncated",
+    ).notNull(),
+    snapshotSource: text("snapshot_source").notNull(),
+    snapshotHash: text("snapshot_hash").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    logicalTurn: uniqueIndex("company_brain_turn_context_snapshot_turn_uq").on(
+      table.workspaceId,
+      table.turnId,
+    ),
+    workspaceIdentity: uniqueIndex("company_brain_turn_context_snapshot_workspace_id_uq").on(
+      table.workspaceId,
+      table.id,
+    ),
+  }),
+);