@opengeni/db 0.36.0 → 1.0.1

package/src/persistence-errors.ts

@@ -25,6 +25,26 @@ export type PersistenceFailureDetails = {
 
 const SQLSTATE_KEYS = ["sqlState", "sqlstate", "code"] as const;
 const NESTED_ERROR_KEYS = ["cause", "original", "driverError", "error", "errors"] as const;
+const RETRYABLE_DATABASE_TRANSPORT_CODES = new Set([
+  // postgres.js connection lifecycle failures.
+  "CONNECTION_CLOSED",
+  "CONNECTION_DESTROYED",
+  "CONNECTION_ENDED",
+  "CONNECT_TIMEOUT",
+  // Node socket/DNS failures surfaced unchanged by postgres.js.
+  "EAI_AGAIN",
+  "ECONNABORTED",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "EHOSTDOWN",
+  "EHOSTUNREACH",
+  "ENETDOWN",
+  "ENETRESET",
+  "ENETUNREACH",
+  "ENOTFOUND",
+  "EPIPE",
+  "ETIMEDOUT",
+]);
 const DATABASE_ERROR_NAMES = new Set(["DatabaseError", "DrizzleQueryError", "PostgresError"]);
 const DATABASE_DIAGNOSTIC_KEYS = [
   "severity",
@@ -72,6 +92,9 @@ export function nestedPostgresSqlState(error: unknown): string | null {
       const value = current[key];
       if (typeof value !== "string" || !/^[0-9A-Z]{5}$/i.test(value)) continue;
       const normalized = value.toUpperCase();
+      // Node transport codes such as EPIPE happen to be five characters but
+      // are not PostgreSQL SQLSTATEs.
+      if (RETRYABLE_DATABASE_TRANSPORT_CODES.has(normalized)) continue;
       if (normalized === "40P01" || normalized === "40001") return normalized;
       fallback ??= normalized;
     }
@@ -94,13 +117,49 @@ export function isRetryablePersistenceSqlState(sqlState: string | null): boolean
   return sqlState === "40P01" || sqlState === "40001";
 }
 
+/**
+ * Recognize only explicit postgres.js/Node transport codes, including nested
+ * driver causes. These failures can arrive as plain Errors with no SQLSTATE or
+ * database diagnostic fields when the connection dies before PostgreSQL can
+ * answer. Messages are intentionally ignored: they are unstable and may
+ * contain connection detail.
+ */
+export function isRetryableDatabaseTransportFailure(error: unknown): boolean {
+  const queue: unknown[] = [error];
+  const seen = new Set<unknown>();
+  while (queue.length > 0 && seen.size < 64) {
+    const current = queue.shift();
+    if (!isRecord(current) || seen.has(current)) continue;
+    seen.add(current);
+
+    for (const key of ["code", "errno"] as const) {
+      const value = current[key];
+      if (
+        typeof value === "string" &&
+        RETRYABLE_DATABASE_TRANSPORT_CODES.has(value.toUpperCase())
+      ) {
+        return true;
+      }
+    }
+
+    for (const key of NESTED_ERROR_KEYS) {
+      const nested = current[key];
+      if (Array.isArray(nested)) queue.push(...nested);
+      else if (nested !== undefined) queue.push(nested);
+    }
+  }
+  return false;
+}
+
 /**
  * Distinguish database/ORM failures from expected domain exceptions when a
  * driver omitted SQLSTATE. This checks shape only; callers retain the original
  * failure independently as canonical error evidence.
  */
 export function isDatabasePersistenceFailure(error: unknown): boolean {
-  if (nestedPostgresSqlState(error) !== null) return true;
+  if (isRetryableDatabaseTransportFailure(error) || nestedPostgresSqlState(error) !== null) {
+    return true;
+  }
 
   const queue: unknown[] = [error];
   const seen = new Set<unknown>();

package/src/provision-roles.ts

@@ -757,6 +757,42 @@ BEGIN
         ${literal(role)}
       );
     END IF;
+    -- Migration 0243 adds the exact Google Drive object authorization and
+    -- safe-citation projections. Re-converge both capabilities for the same
+    -- supported migrate-then-provision order without granting direct mutation
+    -- of their append-only ACL evidence tables.
+    IF to_regprocedure(
+      format(
+        '%I.google_drive_file_authorized(uuid,uuid,text,uuid)',
+        ${literal(schema)}
+      )
+    ) IS NOT NULL THEN
+      EXECUTE format(
+        'REVOKE ALL ON FUNCTION %I.google_drive_file_authorized(uuid, uuid, text, uuid) FROM PUBLIC',
+        ${literal(schema)}
+      );
+      EXECUTE format(
+        'GRANT EXECUTE ON FUNCTION %I.google_drive_file_authorized(uuid, uuid, text, uuid) TO %I',
+        ${literal(schema)},
+        ${literal(role)}
+      );
+    END IF;
+    IF to_regprocedure(
+      format(
+        '%I.google_drive_document_citation(uuid,uuid,text,uuid,uuid)',
+        ${literal(schema)}
+      )
+    ) IS NOT NULL THEN
+      EXECUTE format(
+        'REVOKE ALL ON FUNCTION %I.google_drive_document_citation(uuid, uuid, text, uuid, uuid) FROM PUBLIC',
+        ${literal(schema)}
+      );
+      EXECUTE format(
+        'GRANT EXECUTE ON FUNCTION %I.google_drive_document_citation(uuid, uuid, text, uuid, uuid) TO %I',
+        ${literal(schema)},
+        ${literal(role)}
+      );
+    END IF;
     IF to_regprocedure(
       format(
         '%I.ensure_managed_human_personal_workspace(uuid,text,uuid)',

package/src/runtime-posture.ts

@@ -44,6 +44,22 @@ const DEDICATED_ARTIFACT_CAPABILITY_ROUTINES = new Set<string>([
 
 const KNOWLEDGE_SOURCE_SYNC_LOCK_AUTHORITY_ROUTINE =
   "knowledge_source_sync_lock_authority(uuid, uuid, uuid)";
+const GOOGLE_DRIVE_FILE_AUTHORIZATION_ROUTINE =
+  "google_drive_file_authorized(uuid, uuid, text, uuid)";
+const GOOGLE_DRIVE_DOCUMENT_CITATION_ROUTINE =
+  "google_drive_document_citation(uuid, uuid, text, uuid, uuid)";
+const GOOGLE_DRIVE_AUTHORITY_TABLES = [
+  "connections",
+  "files",
+  "google_drive_object_acl_evidence",
+  "google_drive_object_acl_principals",
+  "knowledge_document_versions",
+  "knowledge_providers",
+  "knowledge_source_objects",
+  "knowledge_source_sync_index_obligations",
+  "knowledge_source_sync_states",
+  "knowledge_sources",
+] as const;
 const KNOWLEDGE_SOURCE_SYNC_LOCK_AUTHORITY_TABLES = [
   "knowledge_sources",
   "knowledge_source_objects",
@@ -110,6 +126,8 @@ export const RUNTIME_TARGET_SCHEMA_CAPABILITY_ROUTINES = [
   XAI_AUTHORITY_LIVE_ROUTINE,
   XAI_CREATE_CREDENTIAL_ROUTINE,
   XAI_DISCONNECT_CREDENTIAL_ROUTINE,
+  GOOGLE_DRIVE_DOCUMENT_CITATION_ROUTINE,
+  GOOGLE_DRIVE_FILE_AUTHORIZATION_ROUTINE,
   KNOWLEDGE_SOURCE_SYNC_LOCK_AUTHORITY_ROUTINE,
   MANAGED_HUMAN_PERSONAL_WORKSPACE_ROUTINE,
   ...CANONICAL_HUMAN_IDENTITY_ROUTINES,
@@ -214,6 +232,8 @@ export const FORCE_RLS_TABLES = [
   "generated_video_artifacts",
   "github_installation_repositories",
   "github_installations",
+  "google_drive_object_acl_evidence",
+  "google_drive_object_acl_principals",
   "host_export_config",
   "host_export_consumers",
   "host_export_cursor_state",
@@ -579,6 +599,8 @@ export const RUNTIME_READ_INSERT_TABLES = [
   "editable_artifact_transactions",
   "editable_artifact_undo_claims",
   "editable_artifact_versions",
+  "google_drive_object_acl_evidence",
+  "google_drive_object_acl_principals",
   "knowledge_change_proposals",
   "knowledge_claim_evidence",
   "knowledge_claim_relations",
@@ -1260,7 +1282,33 @@ export function evaluateRuntimeDatabasePosture(
     } else if (!routine.securityDefiner) {
       violations.push(`target-schema runtime capability ${routine.name} is not SECURITY DEFINER`);
     }
-    if (routine.name === KNOWLEDGE_SOURCE_SYNC_LOCK_AUTHORITY_ROUTINE) {
+    if (
+      routine.name === GOOGLE_DRIVE_FILE_AUTHORIZATION_ROUTINE ||
+      routine.name === GOOGLE_DRIVE_DOCUMENT_CITATION_ROUTINE
+    ) {
+      const missingAuthorityTables = GOOGLE_DRIVE_AUTHORITY_TABLES.filter(
+        (tableName) => !tableByName.has(tableName),
+      );
+      if (missingAuthorityTables.length > 0) {
+        violations.push(
+          `target-schema runtime capability ${routine.name} authority tables are missing: ${missingAuthorityTables.join(", ")}`,
+        );
+      } else {
+        const authorityTables = GOOGLE_DRIVE_AUTHORITY_TABLES.map(
+          (tableName) => tableByName.get(tableName)!,
+        );
+        const authorityOwners = new Set(authorityTables.map((table) => table.owner));
+        if (authorityOwners.size !== 1) {
+          violations.push(
+            `target-schema runtime capability ${routine.name} authority table owners do not match: ${authorityTables.map((table) => `${table.name}=${table.owner}`).join(", ")}`,
+          );
+        } else if (routine.owner !== authorityTables[0]!.owner) {
+          violations.push(
+            `target-schema runtime capability ${routine.name} owner ${routine.owner} does not match authority table owner ${authorityTables[0]!.owner}`,
+          );
+        }
+      }
+    } else if (routine.name === KNOWLEDGE_SOURCE_SYNC_LOCK_AUTHORITY_ROUTINE) {
       const missingAuthorityTables = KNOWLEDGE_SOURCE_SYNC_LOCK_AUTHORITY_TABLES.filter(
         (tableName) => !tableByName.has(tableName),
       );

package/src/schema.ts

@@ -2464,10 +2464,10 @@ export const sessions = pgTable(
     status: text("status").notNull().default("queued"),
     initialMessage: losslessText("initial_message").notNull(),
     initialMessageCodecVersion: losslessCodecVersion("initial_message_codec_version"),
-    // 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"),
+    // Model-visible application context frozen with the winning create. The
+    // initial turn copies it into the canonical user message so an idempotent
+    // repair cannot adopt a retrying caller's different message context.
+    initialModelContext: text("initial_model_context"),
     title: text("title"),
     titleSource: text("title_source"),
     // Per-session agent persona/system instructions supplied at create (the
@@ -2762,6 +2762,11 @@ export const sessions = pgTable(
       table.rootSessionId,
       table.nestedAgentDepth,
     ),
+    initialModelContextValid: check(
+      "sessions_initial_model_context_check",
+      sql`${table.initialModelContext} is null
+        or opengeni_private.model_context_value_valid(${table.initialModelContext})`,
+    ),
   }),
 );
 
@@ -3115,6 +3120,9 @@ export const sessionRealtimeEntries = pgTable(
     textCodecVersion: losslessCodecVersion("text_codec_version"),
     payload: losslessJsonb("payload").$type<Record<string, unknown>>().notNull().default({}),
     payloadCodecVersion: losslessCodecVersion("payload_codec_version"),
+    // Application context for an exact provider-in delegation or finalized
+    // transcript. It is materialized as ordinary user-role message content.
+    modelContext: text("model_context"),
     clientAckedAt: timestamp("client_acked_at", { withTimezone: true }),
     providerAckedAt: timestamp("provider_acked_at", { withTimezone: true }),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
@@ -3190,6 +3198,15 @@ export const sessionRealtimeEntries = pgTable(
         or (${table.kind} = 'assistant_transcript' and ${table.role} = 'assistant' and ${table.text} is not null)
         or (${table.kind} not in ('user_transcript', 'assistant_transcript') and ${table.role} is null)`,
     ),
+    modelContextValid: check(
+      "session_realtime_entries_model_context_check",
+      sql`${table.modelContext} is null
+        or (
+          ${table.direction} = 'provider_in'
+          and ${table.kind} in ('delegation_call', 'user_transcript', 'assistant_transcript')
+          and opengeni_private.model_context_value_valid(${table.modelContext})
+        )`,
+    ),
   }),
 );
 
@@ -4497,9 +4514,10 @@ export const sessionTurns = pgTable(
     prompt: losslessText("prompt").notNull(),
     promptCodecVersion: losslessCodecVersion("prompt_codec_version"),
     annotations: jsonb("annotations").$type<TimelineAnnotation[]>().notNull().default([]),
-    // Host context for this exact turn. System-level at runtime and deliberately
-    // separate from the visible prompt/event payload.
-    turnInstructions: text("turn_instructions"),
+    // Application context for this exact user message. It is copied into the
+    // canonical user-role history item at claim and omitted from public queue
+    // projections; full event/audit data retains it.
+    modelContext: text("model_context"),
     resources: jsonb("resources").$type<unknown[]>().notNull().default([]),
     tools: jsonb("tools").$type<unknown[]>().notNull().default([]),
     // false = inherit the durable session policy; true = this turn explicitly
@@ -4579,6 +4597,11 @@ export const sessionTurns = pgTable(
       "session_turns_latency_mode_check",
       sql`${table.latencyMode} in ('standard', 'priority', 'fast')`,
     ),
+    modelContextValid: check(
+      "session_turns_model_context_check",
+      sql`${table.modelContext} is null
+        or opengeni_private.model_context_value_valid(${table.modelContext})`,
+    ),
   }),
 );
 

package/src/session-queue-commands.ts

@@ -1414,7 +1414,7 @@ export async function submitHumanPromptInTransaction(
     expectedDraftRevision?: number | null;
     text: string;
     annotations?: TimelineAnnotation[];
-    turnInstructions?: string | null;
+    modelContext?: string | null;
     resources: ResourceRef[];
     model?: string | null;
     reasoningEffort?: ReasoningEffort | null;
@@ -1458,7 +1458,7 @@ export async function submitHumanPromptInTransaction(
     expectedDraftRevision: input.expectedDraftRevision ?? null,
     text: input.text,
     annotations,
-    turnInstructions: input.turnInstructions ?? null,
+    modelContext: input.modelContext ?? null,
     resources: withCanonicalResourceMountPaths(input.resources),
     model: input.model ?? null,
     reasoningEffort: input.reasoningEffort ?? null,
@@ -1626,7 +1626,7 @@ export async function submitHumanPromptInTransaction(
   }
 
   let editedSourceTurn: QueuedTurnRow | undefined;
-  let editedSourceTurnInstructions: string | null | undefined;
+  let editedSourceModelContext: string | null | undefined;
   if (draft?.sourceTurnId) {
     const sourceLocks = await lockSessionEventWriteRows(db, {
       workspaceId: input.workspaceId,
@@ -1661,14 +1661,11 @@ export async function submitHumanPromptInTransaction(
         },
       );
     }
-    // This is the sole private-instruction source for an edited replacement.
-    // It is deliberately held separately from the public draft and event
-    // projections below. The public draft is expected to differ after editing;
-    // source identity is fenced by its exact withdrawn row version, not by
-    // comparing the replacement content with the old prompt. A client-supplied
-    // instruction value must never override the private source value.
+    // Preserve the non-rendered message segment when editing only the visible
+    // draft. Source identity is fenced by the exact withdrawn row version; a
+    // replacement request cannot accidentally detach or replace its context.
     editedSourceTurn = sourceTurn;
-    editedSourceTurnInstructions = sourceTurn.turnInstructions ?? null;
+    editedSourceModelContext = sourceTurn.modelContext ?? null;
   }
 
   for (const update of input.mcpCredentialUpdates ?? []) {
@@ -1725,6 +1722,10 @@ export async function submitHumanPromptInTransaction(
   const acceptedEventId = crypto.randomUUID();
   const turnId = crypto.randomUUID();
   const workflowId = session.temporalWorkflowId ?? `session-${session.id}`;
+  const effectiveModelContext =
+    editedSourceModelContext !== undefined
+      ? editedSourceModelContext
+      : (input.modelContext ?? null);
   let sequence = session.lastSequence;
   const eventValues: SessionEventInsertWithPayload[] = [
     {
@@ -1747,6 +1748,7 @@ export async function submitHumanPromptInTransaction(
             }
           : {}),
         ...(input.resources.length ? { resources: input.resources } : {}),
+        ...(effectiveModelContext ? { modelContext: effectiveModelContext } : {}),
         ...(input.model ? { model: input.model } : {}),
         ...(input.reasoningEffort ? { reasoningEffort: input.reasoningEffort } : {}),
         ...(input.latencyMode ? { latencyMode: input.latencyMode } : {}),
@@ -1773,10 +1775,7 @@ export async function submitHumanPromptInTransaction(
           position: input.delivery === "steer" ? 0 : existingQueued.length + 1,
           prompt: input.text,
           annotations,
-          turnInstructions:
-            editedSourceTurnInstructions !== undefined
-              ? editedSourceTurnInstructions
-              : (input.turnInstructions ?? null),
+          modelContext: effectiveModelContext,
           resources: input.resources,
           tools: [],
           toolsProvided: false,

package/src/session-realtime-context.ts

@@ -237,6 +237,7 @@ export async function flushSessionRealtimeTranscriptTailInTransaction(
       textCodecVersion: schema.sessionRealtimeEntries.textCodecVersion,
       payload: schema.sessionRealtimeEntries.payload,
       payloadCodecVersion: schema.sessionRealtimeEntries.payloadCodecVersion,
+      modelContext: schema.sessionRealtimeEntries.modelContext,
     })
     .from(schema.sessionRealtimeEntries)
     .where(
@@ -258,6 +259,20 @@ export async function flushSessionRealtimeTranscriptTailInTransaction(
   }));
   const rendered = renderSessionRealtimeTail(decodedRows);
   if (!rendered.context) return null;
+  const renderedRows = decodedRows.slice(decodedRows.length - rendered.includedEntryCount);
+  let foundUserTranscript = false;
+  let modelContext: string | null = null;
+  for (let index = renderedRows.length - 1; index >= 0; index -= 1) {
+    const entry = renderedRows[index]!;
+    if (entry.role === "user") {
+      foundUserTranscript = true;
+      modelContext = entry.modelContext;
+      break;
+    }
+  }
+  if (!foundUserTranscript) {
+    modelContext = renderedRows.at(-1)?.modelContext ?? null;
+  }
 
   const [session] = await db
     .select({ metadata: schema.sessions.metadata })
@@ -286,6 +301,7 @@ export async function flushSessionRealtimeTranscriptTailInTransaction(
     operationKey: deterministicUuid(`opengeni:session-realtime-tail-flush:${mode.id}`),
     delivery: "steer",
     text: rendered.context,
+    modelContext,
     messagePresentation: {
       kind: "realtime_voice_handoff",
       text: "Voice session ended. Remaining conversation context was sent to the agent.",

package/src/session-realtime-ledger.ts

@@ -155,6 +155,7 @@ export type SessionRealtimeInboundEntryInput = {
   delegationItemId?: string | null | undefined;
   text?: string | null | undefined;
   payload?: Record<string, unknown> | undefined;
+  modelContext?: string | undefined;
 };
 
 export type SyncSessionRealtimeLedgerInput = AssertSessionRealtimeOwnerInput & {
@@ -1016,12 +1017,34 @@ function canonicalJsonValue(value: unknown): unknown {
   return value;
 }
 
+function normalizedModelContext(input: SessionRealtimeInboundEntryInput): string | null {
+  const value = input.modelContext?.trim();
+  if (!value) {
+    if (input.modelContext !== undefined) {
+      throw new Error("Realtime modelContext must not be empty");
+    }
+    return null;
+  }
+  if (value.length > 32_768) {
+    throw new Error("Realtime modelContext exceeds the server limit");
+  }
+  if (
+    input.kind !== "delegation_call" &&
+    input.kind !== "user_transcript" &&
+    input.kind !== "assistant_transcript"
+  ) {
+    throw new Error("Realtime modelContext requires a delegation or finalized transcript");
+  }
+  return value;
+}
+
 function inboundReplayMatches(
   row: EntryRow,
   input: SessionRealtimeInboundEntryInput,
   role: "user" | "assistant" | null,
   text: string | null,
   payload: Record<string, unknown>,
+  modelContext: string | null,
 ): boolean {
   const storedText =
     row.text === null ? null : fromPostgresLosslessText(row.text, row.textCodecVersion);
@@ -1034,11 +1057,32 @@ function inboundReplayMatches(
     row.delegationItemId === (input.delegationItemId ?? null) &&
     row.sourceUpdateId === null &&
     storedText === text &&
+    row.modelContext === modelContext &&
     JSON.stringify(canonicalJsonValue(storedPayload)) ===
       JSON.stringify(canonicalJsonValue(payload))
   );
 }
 
+async function delegationModelContextMatches(
+  db: Database,
+  row: EntryRow,
+  modelContext: string | null,
+): Promise<boolean> {
+  if (row.kind !== "delegation_call" || row.turnId === null) return true;
+  const [turn] = await db
+    .select({ modelContext: schema.sessionTurns.modelContext })
+    .from(schema.sessionTurns)
+    .where(
+      and(
+        eq(schema.sessionTurns.workspaceId, row.workspaceId),
+        eq(schema.sessionTurns.sessionId, row.sessionId),
+        eq(schema.sessionTurns.id, row.turnId),
+      ),
+    )
+    .limit(1);
+  return turn?.modelContext === modelContext;
+}
+
 async function appendInvalidDelegationFailure(
   db: Database,
   input: Pick<
@@ -1083,6 +1127,7 @@ async function admitRealtimeDelegationInTransaction(
   accountId: string,
   incoming: SessionRealtimeInboundEntryInput,
   entryId: string,
+  modelContext: string | null,
 ): Promise<{ turnId: string; eventIds: string[]; wakeRevision: number }> {
   const [session] = await db
     .select()
@@ -1142,6 +1187,7 @@ async function admitRealtimeDelegationInTransaction(
     operationKey: incoming.operationId,
     delivery: "steer",
     text: incoming.text!,
+    modelContext,
     messagePresentation: {
       kind: "realtime_voice",
       text: inputTranscript,
@@ -1359,6 +1405,7 @@ export async function syncSessionRealtimeLedgerInTransaction(
     const payload = boundedPayload(incoming.payload);
     const role = expectedRole(incoming);
     const text = incoming.text ?? null;
+    const modelContext = normalizedModelContext(incoming);
     assertBoundedString(text, SESSION_REALTIME_LEDGER_MAX_TEXT_BYTES, "Realtime text");
     if (
       (incoming.kind === "user_transcript" || incoming.kind === "assistant_transcript") &&
@@ -1392,7 +1439,10 @@ export async function syncSessionRealtimeLedgerInTransaction(
       )
       .limit(1);
     if (existing) {
-      if (!inboundReplayMatches(existing, incoming, role, text, payload)) {
+      if (
+        !inboundReplayMatches(existing, incoming, role, text, payload, modelContext) ||
+        !(await delegationModelContextMatches(db, existing, modelContext))
+      ) {
         throw new SessionRealtimeConflictError(
           incoming.kind === "delegation_call"
             ? "REALTIME_DELEGATION_CHANGED"
@@ -1423,6 +1473,7 @@ export async function syncSessionRealtimeLedgerInTransaction(
         textCodecVersion: LOSSLESS_CONTENT_CODEC_VERSION,
         payload,
         payloadCodecVersion: LOSSLESS_CONTENT_CODEC_VERSION,
+        modelContext,
         createdAt: now,
         updatedAt: now,
       })
@@ -1447,6 +1498,7 @@ export async function syncSessionRealtimeLedgerInTransaction(
           modeRow.accountId,
           incoming,
           entry.id,
+          modelContext,
         );
         const [linked] = await db
           .update(schema.sessionRealtimeEntries)