@opengeni/db 0.23.0 → 0.26.0

package/src/index.ts

@@ -14,6 +14,7 @@ import type {
   ConnectionKind,
   ConnectionMetadata,
   ConnectionStatus,
+  DocumentAuthorityKind,
   McpServerConnectionRef,
   FileAsset,
   FileStatus,
@@ -111,6 +112,7 @@ import {
   decodeNativeSnapshotRef,
   parseWorkspaceArchiveDescriptor,
   stableJson,
+  MODEL_ATTACHMENT_REFS_FIELD,
 } from "@opengeni/contracts";
 
 import {
@@ -232,6 +234,11 @@ import {
   projectSessionRealtimeDelegationProgressInTransaction,
   projectSessionRealtimeDelegationTerminalInTransaction,
 } from "./session-realtime-ledger";
+import {
+  mirrorSessionRealtimeContextInTransaction,
+  renderRealtimeHumanInputRequestContext,
+  renderRealtimeHumanInputResponseContext,
+} from "./session-realtime-mirror";
 import {
   listSessionRealtimeContinuityEntriesInTransaction,
   type SessionRealtimeContinuityEntry,
@@ -1197,6 +1204,55 @@ export async function withWorkspaceUsageLock<T>(
   });
 }
 
+export type DocumentIndexAuthority = {
+  authorityKind: DocumentAuthorityKind;
+  authorityWorkspaceId: string | null;
+  authoritySubjectId: string | null;
+};
+
+/**
+ * Read the immutable authority tuple used by document indexing compatibility.
+ * The database capability returns no document content and independently
+ * verifies that this transaction already carries the exact account/workspace
+ * RLS context. It is intentionally subject-free so a historical three-field
+ * Temporal payload can recover a personal document's frozen subject without
+ * weakening ordinary document visibility.
+ */
+export async function resolveDocumentIndexAuthority(
+  db: Database,
+  input: { accountId: string; workspaceId: string; documentId: string },
+): Promise<DocumentIndexAuthority | null> {
+  const rows = await rawRows<{
+    authority_kind: string;
+    authority_workspace_id: string | null;
+    authority_subject_id: string | null;
+  }>(
+    db,
+    sql`
+      select authority_kind, authority_workspace_id, authority_subject_id
+      from opengeni_private.resolve_document_index_authority(
+        ${input.accountId},
+        ${input.workspaceId},
+        ${input.documentId}
+      )
+    `,
+  );
+  const row = rows[0];
+  if (!row) return null;
+  if (
+    row.authority_kind !== "organization" &&
+    row.authority_kind !== "workspace" &&
+    row.authority_kind !== "personal"
+  ) {
+    throw new Error(`Stored document authority kind is invalid: ${row.authority_kind}`);
+  }
+  return {
+    authorityKind: row.authority_kind,
+    authorityWorkspaceId: row.authority_workspace_id,
+    authoritySubjectId: row.authority_subject_id,
+  };
+}
+
 export async function withAccountRls<T>(
   db: Database,
   accountId: string,
@@ -3498,6 +3554,47 @@ export type UpdateConnectionInput = {
   updatedBySubjectId?: string | null;
 };
 
+export type TransitionConnectionStateInput = {
+  workspaceId: string;
+  connectionId: string;
+  visibleToSubjectId?: string | null;
+  expectedVersion: number;
+  status?: ConnectionStatus;
+  metadata: Record<string, unknown>;
+  lastError?: string | null;
+  updatedBySubjectId?: string | null;
+};
+
+export type DisconnectConnectionIdempotentlyInput = {
+  accountId: string;
+  workspaceId: string;
+  subjectId: string;
+  connectionId: string;
+  expectedVersion: number;
+  idempotencyKey: string;
+  metadata: Record<string, unknown>;
+  lastError?: string | null;
+  updatedBySubjectId?: string | null;
+};
+
+export class ConnectionDisconnectIdempotencyError extends Error {
+  readonly code = "IDEMPOTENCY_KEY_REUSED";
+
+  constructor() {
+    super("The disconnect idempotency key was already used with different input");
+    this.name = "ConnectionDisconnectIdempotencyError";
+  }
+}
+
+export class ConnectionDisconnectGenerationError extends Error {
+  readonly code = "CONNECTION_GENERATION_CHANGED";
+
+  constructor() {
+    super("The disconnect operation belongs to an older connection generation");
+    this.name = "ConnectionDisconnectGenerationError";
+  }
+}
+
 /** Server-owned verification facts; public schemas expose them read-only and nullable. */
 export type ConnectionMetadataWithVerification = ConnectionMetadata & {
   verifiedInstallAt: string | null;
@@ -3880,6 +3977,39 @@ export async function requireFile(
   return file;
 }
 
+/** One RLS-scoped query for all attachment metadata needed by a model turn. */
+export async function getFiles(
+  db: Database,
+  workspaceId: string,
+  fileIds: readonly string[],
+): Promise<FileAsset[]> {
+  const ids = [...new Set(fileIds)];
+  if (ids.length === 0) return [];
+  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    const rows = await scopedDb
+      .select()
+      .from(schema.files)
+      .where(and(eq(schema.files.workspaceId, workspaceId), inArray(schema.files.id, ids)));
+    return rows.map(mapFile);
+  });
+}
+
+/** Build the canonical user row with stable attachment refs, never inline bytes. */
+export function durableUserHistoryItem(
+  prompt: string,
+  resources: readonly ResourceRef[],
+): Record<string, unknown> {
+  const attachmentRefs = resources.filter(
+    (resource): resource is Extract<ResourceRef, { kind: "file" }> => resource.kind === "file",
+  );
+  return sanitizeModelPayload({
+    type: "message",
+    role: "user",
+    content: prompt,
+    ...(attachmentRefs.length > 0 ? { [MODEL_ATTACHMENT_REFS_FIELD]: attachmentRefs } : {}),
+  });
+}
+
 export type RetainedFileArtifact = {
   file: FileAsset;
   uploadStatus: FileUploadStatus | null;
@@ -5327,6 +5457,191 @@ export async function updateConnection(
   );
 }
 
+async function transitionConnectionStateInScope(
+  db: Database,
+  input: TransitionConnectionStateInput,
+): Promise<ConnectionMetadataWithVerification | null> {
+  const [row] = await db
+    .update(schema.connections)
+    .set({
+      ...(input.status !== undefined ? { status: input.status } : {}),
+      metadata: input.metadata,
+      ...(input.lastError !== undefined ? { lastError: input.lastError } : {}),
+      version: sql`${schema.connections.version} + 1`,
+      ...(input.updatedBySubjectId !== undefined
+        ? { updatedBySubjectId: input.updatedBySubjectId }
+        : {}),
+      updatedAt: new Date(),
+    })
+    .where(
+      and(
+        eq(schema.connections.workspaceId, input.workspaceId),
+        eq(schema.connections.id, input.connectionId),
+        connectionSubjectVisibility(input.visibleToSubjectId),
+        eq(schema.connections.version, input.expectedVersion),
+      ),
+    )
+    .returning(connectionMetadataColumns);
+  return row ? mapConnectionMetadata(row) : null;
+}
+
+/**
+ * Applies a metadata/status lifecycle transition behind the connection's
+ * existing `(id, version)` fence. Unlike ordinary metadata edits, every
+ * transition advances the version so concurrent refresh, disconnect,
+ * reconnect, source-selection, and lifecycle operations cannot overwrite one
+ * another from stale snapshots.
+ */
+export async function transitionConnectionState(
+  db: Database,
+  input: TransitionConnectionStateInput,
+): Promise<ConnectionMetadataWithVerification | null> {
+  return await withConnectionSubjectRls(
+    db,
+    input.workspaceId,
+    input.visibleToSubjectId,
+    async (scopedDb) => await transitionConnectionStateInScope(scopedDb, input),
+  );
+}
+
+const connectionDisconnectOperationColumns = {
+  accountId: schema.connectionDisconnectOperations.accountId,
+  workspaceId: schema.connectionDisconnectOperations.workspaceId,
+  connectionId: schema.connectionDisconnectOperations.connectionId,
+  subjectId: schema.connectionDisconnectOperations.subjectId,
+  idempotencyKey: schema.connectionDisconnectOperations.idempotencyKey,
+  expectedVersion: schema.connectionDisconnectOperations.expectedVersion,
+  resultVersion: schema.connectionDisconnectOperations.resultVersion,
+};
+
+/**
+ * Disconnects one exact subject-owned connection generation and records the
+ * caller's durable operation identity in the same transaction. Exact retries
+ * converge only while the produced generation remains current; a reconnect or
+ * any other later transition fences the old operation permanently.
+ */
+export async function disconnectConnectionIdempotently(
+  db: Database,
+  input: DisconnectConnectionIdempotentlyInput,
+): Promise<ConnectionMetadataWithVerification | null> {
+  return await withConnectionSubjectRls(
+    db,
+    input.workspaceId,
+    input.subjectId,
+    async (scopedDb) => {
+      const [connectionRow] = await scopedDb
+        .select(connectionMetadataColumns)
+        .from(schema.connections)
+        .where(
+          and(
+            eq(schema.connections.accountId, input.accountId),
+            eq(schema.connections.workspaceId, input.workspaceId),
+            eq(schema.connections.id, input.connectionId),
+            eq(schema.connections.subjectId, input.subjectId),
+          ),
+        )
+        .for("update");
+      if (!connectionRow) return null;
+      const connection = mapConnectionMetadata(connectionRow);
+
+      const [replayed] = await scopedDb
+        .select(connectionDisconnectOperationColumns)
+        .from(schema.connectionDisconnectOperations)
+        .where(
+          and(
+            eq(schema.connectionDisconnectOperations.workspaceId, input.workspaceId),
+            eq(schema.connectionDisconnectOperations.subjectId, input.subjectId),
+            eq(schema.connectionDisconnectOperations.idempotencyKey, input.idempotencyKey),
+          ),
+        )
+        .limit(1);
+      if (replayed) {
+        if (
+          replayed.accountId !== input.accountId ||
+          replayed.connectionId !== input.connectionId ||
+          replayed.expectedVersion !== input.expectedVersion
+        ) {
+          throw new ConnectionDisconnectIdempotencyError();
+        }
+        if (connection.version !== replayed.resultVersion) {
+          throw new ConnectionDisconnectGenerationError();
+        }
+        return connection;
+      }
+
+      if (connection.version !== input.expectedVersion) {
+        throw new ConnectionDisconnectGenerationError();
+      }
+
+      const [inserted] = await scopedDb
+        .insert(schema.connectionDisconnectOperations)
+        .values({
+          accountId: input.accountId,
+          workspaceId: input.workspaceId,
+          connectionId: input.connectionId,
+          subjectId: input.subjectId,
+          idempotencyKey: input.idempotencyKey,
+          expectedVersion: input.expectedVersion,
+          resultVersion: input.expectedVersion + 1,
+        })
+        .onConflictDoNothing()
+        .returning(connectionDisconnectOperationColumns);
+      if (!inserted) {
+        const [conflictingKey] = await scopedDb
+          .select(connectionDisconnectOperationColumns)
+          .from(schema.connectionDisconnectOperations)
+          .where(
+            and(
+              eq(schema.connectionDisconnectOperations.workspaceId, input.workspaceId),
+              eq(schema.connectionDisconnectOperations.subjectId, input.subjectId),
+              eq(schema.connectionDisconnectOperations.idempotencyKey, input.idempotencyKey),
+            ),
+          )
+          .limit(1);
+        if (
+          !conflictingKey ||
+          conflictingKey.accountId !== input.accountId ||
+          conflictingKey.connectionId !== input.connectionId ||
+          conflictingKey.expectedVersion !== input.expectedVersion
+        ) {
+          throw new ConnectionDisconnectIdempotencyError();
+        }
+        if (connection.version !== conflictingKey.resultVersion) {
+          throw new ConnectionDisconnectGenerationError();
+        }
+        return connection;
+      }
+
+      const [updated] = await scopedDb
+        .update(schema.connections)
+        .set({
+          status: "revoked",
+          metadata: input.metadata,
+          ...(input.lastError !== undefined ? { lastError: input.lastError } : {}),
+          version: sql`${schema.connections.version} + 1`,
+          ...(input.updatedBySubjectId !== undefined
+            ? { updatedBySubjectId: input.updatedBySubjectId }
+            : {}),
+          updatedAt: new Date(),
+        })
+        .where(
+          and(
+            eq(schema.connections.accountId, input.accountId),
+            eq(schema.connections.workspaceId, input.workspaceId),
+            eq(schema.connections.id, input.connectionId),
+            eq(schema.connections.subjectId, input.subjectId),
+            eq(schema.connections.version, input.expectedVersion),
+          ),
+        )
+        .returning(connectionMetadataColumns);
+      if (!updated) {
+        throw new ConnectionDisconnectGenerationError();
+      }
+      return mapConnectionMetadata(updated);
+    },
+  );
+}
+
 async function revokeConnectionInScope(
   db: Database,
   workspaceId: string,
@@ -5371,13 +5686,20 @@ export async function revokeConnection(
   workspaceId: string,
   connectionId: string,
   updatedBySubjectId?: string | null,
+  expectedVersion?: number,
 ): Promise<ConnectionMetadataWithVerification | null> {
   return await withConnectionSubjectRls(
     db,
     workspaceId,
     updatedBySubjectId,
     async (scopedDb) =>
-      await revokeConnectionInScope(scopedDb, workspaceId, connectionId, updatedBySubjectId),
+      await revokeConnectionInScope(
+        scopedDb,
+        workspaceId,
+        connectionId,
+        updatedBySubjectId,
+        expectedVersion,
+      ),
   );
 }
 
@@ -20364,21 +20686,9 @@ function validateAnsweredHumanInput(
           `Text question ${question.id} accepts one value`,
         );
       }
-      const value = values[0] ?? "";
-      const minLength = question.validation?.minLength;
-      const maxLength = question.validation?.maxLength;
-      if (minLength != null && value.length < minLength) {
-        throw new HumanInputResponseValidationError(
-          "INVALID_RESPONSE",
-          `Question ${question.id} is shorter than its minimum length`,
-        );
-      }
-      if (maxLength != null && value.length > maxLength) {
-        throw new HumanInputResponseValidationError(
-          "INVALID_RESPONSE",
-          `Question ${question.id} exceeds its maximum length`,
-        );
-      }
+      // Text answers have no agent-chosen char bounds — only the platform
+      // string cap on HumanInputAnswer.values. Ignore legacy minLength/maxLength
+      // still present on older persisted question JSON.
       continue;
     }
     if (other && !question.allowOther) {
@@ -20689,6 +20999,27 @@ export async function acceptSessionHumanInputResponse(
           })
           .returning();
         if (!event) throw new Error("Failed to append human-input response");
+        await mirrorSessionRealtimeContextInTransaction(tx as unknown as Database, {
+          accountId: session.accountId,
+          workspaceId: input.workspaceId,
+          sessionId: input.sessionId,
+          sourceKind: "human_input_response",
+          sourceId: event.id,
+          turnId: turn.id,
+          channel:
+            response.outcome === "answered" || response.outcome === "skipped" ? "speakable" : null,
+          text: renderRealtimeHumanInputResponseContext({
+            requestId: request.id,
+            questions: request.questions,
+            response,
+          }),
+          payload: {
+            requestId: request.id,
+            outcome: response.outcome,
+            sourceEventId: event.id,
+          },
+          now,
+        });
         await tx
           .update(schema.sessions)
           .set({ lastSequence: session.lastSequence + 1, updatedAt: now })
@@ -38173,11 +38504,10 @@ export async function claimSessionWorkForAttempt(
           sessionId,
           turnId: row.id,
           position: Number(historyPosition),
-          item: sanitizeModelPayload({
-            type: "message",
-            role: "user",
-            content: row.prompt,
-          }),
+          item: durableUserHistoryItem(
+            row.prompt,
+            Array.isArray(row.resources) ? (row.resources as ResourceRef[]) : [],
+          ),
           producerCodexCredentialId: null,
         });
         const providerDelegatedTurn = isSessionRealtimeDelegationTurnMetadata(row.metadata);
@@ -39912,11 +40242,11 @@ export async function applySessionTurnSettlement(
         };
       }
 
+      const humanInputRequests = input.runState?.humanInputRequests ?? [];
       if (input.runState) {
         if (input.turnStatus !== "requires_action" || input.sessionStatus !== "requires_action") {
           throw new Error("A frozen run state requires a requires_action settlement");
         }
-        const humanInputRequests = input.runState.humanInputRequests ?? [];
         for (const request of humanInputRequests) {
           const parsedQuestions = request.questions.map((question) =>
             HumanInputQuestionContract.parse(question),
@@ -40168,7 +40498,10 @@ export async function applySessionTurnSettlement(
                 eq(schema.sessionHumanInputRequests.status, "pending"),
               ),
             )
-            .returning({ id: schema.sessionHumanInputRequests.id })
+            .returning({
+              id: schema.sessionHumanInputRequests.id,
+              questions: schema.sessionHumanInputRequests.questions,
+            })
         : [];
       const terminalHumanInputEvents: AppendEventInput[] = terminalHumanInputRows.map(
         (request) => ({
@@ -40251,6 +40584,69 @@ export async function applySessionTurnSettlement(
       });
       const inserted =
         values.length > 0 ? await tx.insert(schema.sessionEvents).values(values).returning() : [];
+      const requestedEvents = inserted.filter(
+        (event) => event.type === "session.humanInput.requested",
+      );
+      if (requestedEvents.length > 0) {
+        const requestedIds = new Set(
+          requestedEvents.flatMap((event) => {
+            const request = sessionEventPayloadRecord(event.payload).request;
+            if (!request || typeof request !== "object" || Array.isArray(request)) return [];
+            const id = (request as Record<string, unknown>).id;
+            return typeof id === "string" ? [id] : [];
+          }),
+        );
+        const requests = humanInputRequests.filter((request) => requestedIds.has(request.id));
+        if (requests.length !== requestedIds.size) {
+          throw new Error("Human-input realtime projection lost its durable request contract");
+        }
+        await mirrorSessionRealtimeContextInTransaction(tx as unknown as Database, {
+          accountId: session.accountId,
+          workspaceId,
+          sessionId: input.sessionId,
+          sourceKind: "human_input_request",
+          sourceId: requestedEvents.map((event) => event.id).join(":"),
+          turnId: input.turnId,
+          channel: "speakable",
+          text: renderRealtimeHumanInputRequestContext({ requests }),
+          payload: {
+            status: "waiting_for_user",
+            requestIds: requests.map((request) => request.id),
+            sourceEventIds: requestedEvents.map((event) => event.id),
+          },
+          now,
+        });
+      }
+      const terminalHumanInputById = new Map(
+        terminalHumanInputRows.map((request) => [request.id, request]),
+      );
+      for (const event of inserted) {
+        if (event.type !== "user.humanInputResponse") continue;
+        const payload = sessionEventPayloadRecord(event.payload);
+        const requestId = typeof payload.requestId === "string" ? payload.requestId : null;
+        const request = requestId ? terminalHumanInputById.get(requestId) : null;
+        if (!request) continue;
+        await mirrorSessionRealtimeContextInTransaction(tx as unknown as Database, {
+          accountId: session.accountId,
+          workspaceId,
+          sessionId: input.sessionId,
+          sourceKind: "human_input_response",
+          sourceId: event.id,
+          turnId: input.turnId,
+          channel: null,
+          text: renderRealtimeHumanInputResponseContext({
+            requestId: request.id,
+            questions: request.questions,
+            response: { outcome: "cancelled" },
+          }),
+          payload: {
+            requestId: request.id,
+            outcome: "cancelled",
+            sourceEventId: event.id,
+          },
+          now,
+        });
+      }
       const terminal = isTerminalSessionTurnStatus(input.turnStatus);
       if (isTerminalSessionTurnStatus(input.turnStatus)) {
         const terminalType = terminalSessionTurnEventType(input.turnStatus);

package/src/preference-registry.ts

@@ -558,6 +558,109 @@ export async function listPreferenceRegistry(
   });
 }
 
+export type PreferenceRegistryGovernanceIdentity = Pick<
+  PreferenceRegistryDescriptor,
+  "id" | "revisionId" | "contentHash" | "activeVersion" | "scope"
+>;
+
+export type CurrentPreferenceRegistryGovernanceMetadata = {
+  descriptors: PreferenceRegistryGovernanceIdentity[];
+  truncated: boolean;
+};
+
+/**
+ * Read the current active descriptor identities for one exact authenticated
+ * subject. Full preference values and even descriptor display text stay inside
+ * this DB boundary; Workspace State receives only stable revision metadata.
+ */
+export async function getCurrentPreferenceRegistryGovernanceMetadata(
+  db: Database,
+  input: { workspaceId: string; subjectId: string },
+): Promise<CurrentPreferenceRegistryGovernanceMetadata> {
+  return await withWorkspaceSubjectRls(db, input.workspaceId, input.subjectId, async (scopedDb) => {
+    const rows = await scopedDb
+      .select({
+        preference: schema.preferenceRegistryPreferences,
+        revision: schema.preferenceRegistryRevisions,
+      })
+      .from(schema.preferenceRegistryPreferences)
+      .innerJoin(
+        schema.preferenceRegistryRevisions,
+        and(
+          eq(
+            schema.preferenceRegistryRevisions.id,
+            schema.preferenceRegistryPreferences.activeRevisionId,
+          ),
+          eq(
+            schema.preferenceRegistryRevisions.accountId,
+            schema.preferenceRegistryPreferences.accountId,
+          ),
+        ),
+      )
+      .where(
+        and(
+          eq(schema.preferenceRegistryPreferences.status, "active"),
+          or(
+            isNull(schema.preferenceRegistryRevisions.expiresAt),
+            gt(schema.preferenceRegistryRevisions.expiresAt, sql`transaction_timestamp()`),
+          ),
+        ),
+      )
+      .orderBy(
+        sql`case ${schema.preferenceRegistryPreferences.scope}
+          when 'organization' then 0
+          when 'workspace' then 1
+          when 'user' then 2
+          else 3
+        end`,
+        desc(schema.preferenceRegistryRevisions.precedenceRank),
+        asc(schema.preferenceRegistryPreferences.stableKey),
+        asc(schema.preferenceRegistryPreferences.id),
+      )
+      .limit(PREFERENCE_REGISTRY_DESCRIPTOR_MAX_COUNT + 1);
+
+    const bounded = boundPreferenceRegistryDescriptors(
+      rows.map(({ preference, revision }) =>
+        PreferenceRegistryDescriptor.parse({
+          id: preference.id,
+          stableKey: preference.stableKey,
+          title: revision.title,
+          description: revision.description,
+          scope: preference.scope,
+          activeVersion: preference.activationVersion,
+          revisionId: revision.id,
+          contentHash: revision.contentHash,
+          precedence: {
+            tier: preference.scope,
+            rank: revision.precedenceRank,
+            conflictStrategy: revision.conflictStrategy,
+            conflictsWith: revision.conflictsWith,
+          },
+          provenance: {
+            source: revision.provenanceSource,
+            sourceIdHash: revision.provenanceSourceId
+              ? contentHash(revision.provenanceSourceId)
+              : null,
+            trust: revision.trust,
+          },
+          expiresAt: revision.expiresAt ? iso(revision.expiresAt) : null,
+          retrievalHandle: `preference://${preference.id}/revisions/${revision.id}?sha256=${revision.contentHash}`,
+        }),
+      ),
+    );
+    return {
+      descriptors: bounded.descriptors.map((descriptor) => ({
+        id: descriptor.id,
+        revisionId: descriptor.revisionId,
+        contentHash: descriptor.contentHash,
+        activeVersion: descriptor.activeVersion,
+        scope: descriptor.scope,
+      })),
+      truncated: bounded.truncated,
+    };
+  });
+}
+
 export async function listPreferenceRegistryForAttempt(
   db: Database,
   input: PreferenceRegistryAttemptClaims & PreferenceRegistryListInput,

package/src/runtime-posture.ts

@@ -24,6 +24,7 @@ export const FORCE_RLS_TABLES = [
   "codex_rotation_settings",
   "codex_subscription_credentials",
   "composer_drafts",
+  "connection_disconnect_operations",
   "connections",
   "connector_action_policies",
   "connector_action_requests",
@@ -176,6 +177,7 @@ export const RUNTIME_FULL_DML_TABLES = [
   "codex_rotation_settings",
   "codex_subscription_credentials",
   "composer_drafts",
+  "connection_disconnect_operations",
   "connections",
   "connector_action_policies",
   "connector_action_requests",