@opengeni/db 0.28.9 → 0.36.0

package/src/session-queue-commands.ts

@@ -1,20 +1,40 @@
 import {
+  WORKSPACE_XAI_PROVIDER_ACCOUNT_AUTHORITY_SNAPSHOT_V1,
+  XaiProviderAccountAuthoritySnapshotV1,
+  DraftTimelineAnnotations,
   McpPersonalConnectionDelegations,
+  TimelineAnnotations,
   metadataWithTurnExecutionPolicyV1,
   mergeResourceRefs,
+  renderTimelineAnnotationsForModel,
   ResourceRef,
   resourceMountPath,
   stableJson,
   turnExecutionPolicyAuditMetadata,
   type McpPersonalConnectionDelegation,
+  type DraftTimelineAnnotation,
   type LatencyMode,
   type ReasoningEffort,
+  type SandboxBackend,
+  type SandboxOs,
+  type SessionEvent,
+  type SessionEventType,
+  type SessionTurn,
+  type SessionTurnSource,
+  type SessionTurnStatus,
+  type ToolRef,
   type TurnExecutionPolicyV1,
+  type TimelineAnnotation,
 } from "@opengeni/contracts";
 import { and, asc, eq, inArray, sql } from "drizzle-orm";
-import type { Database } from "./database";
-import { withLosslessContentWriteVersion } from "./lossless-json";
+import type { Database, SessionActivityDatabase } from "./database";
+import {
+  fromPostgresLosslessJson,
+  fromPostgresLosslessText,
+  withLosslessContentWriteVersion,
+} from "./lossless-json";
 import { closePendingSessionToolCallsInTransaction } from "./session-tool-call-settlement";
+import { cancelTurnInteractionInterventionsInTransaction } from "./browser-auth";
 import {
   assertAgentCommandAuthorityInTransaction,
   autoResumeSessionBranchInTransaction,
@@ -44,6 +64,7 @@ import {
   initiatorFromStorage,
   type FrozenTurnInitiator,
 } from "./turn-initiator";
+import { resolveXaiProviderAccountAuthoritySnapshotForAcceptanceInTransaction } from "./xai-subscription";
 
 type SessionEventInsertWithPayload = typeof schema.sessionEvents.$inferInsert & {
   payload: unknown;
@@ -97,6 +118,10 @@ export type SteerQueueCommandResult = QueueCommandResult & {
 export type SubmitHumanPromptResult = {
   receipt: SessionCommandReceiptRow;
   queueVersion: number;
+  accepted: SessionEvent;
+  events: SessionEvent[];
+  turn: SessionTurn;
+  /** Backward-compatible row identities for lower-level callers. */
   acceptedEventId: string;
   eventIds: string[];
   turnId: string;
@@ -106,6 +131,69 @@ export type SubmitHumanPromptResult = {
   replay: boolean;
 };
 
+function mapSubmittedPromptEvent(row: typeof schema.sessionEvents.$inferSelect): SessionEvent {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    sessionId: row.sessionId,
+    sequence: row.sequence,
+    type: row.type as SessionEventType,
+    payload: fromPostgresLosslessJson(row.payload, row.payloadCodecVersion),
+    occurredAt: row.occurredAt.toISOString(),
+    clientEventId: row.clientEventId,
+    turnId: row.turnId,
+    turnGeneration: row.turnGeneration,
+    turnAttemptId: row.turnAttemptId,
+    turnAssociation: row.turnAssociation as SessionEvent["turnAssociation"],
+    duplicateOfEventId: row.duplicateOfEventId,
+    duplicateReason: row.duplicateReason,
+  };
+}
+
+function mapSubmittedPromptTurn(row: typeof schema.sessionTurns.$inferSelect): SessionTurn {
+  const personalConnections = McpPersonalConnectionDelegations.parse(
+    row.personalConnectionDelegations,
+  ).map(({ serverId, providerDomain }) => ({ serverId, providerDomain }));
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    sessionId: row.sessionId,
+    triggerEventId: row.triggerEventId,
+    temporalWorkflowId: row.temporalWorkflowId,
+    status: row.status as SessionTurnStatus,
+    source: row.source as SessionTurnSource,
+    position: row.position,
+    prompt: fromPostgresLosslessText(row.prompt, row.promptCodecVersion),
+    annotations: TimelineAnnotations.parse(row.annotations),
+    resources: row.resources as ResourceRef[],
+    tools: row.tools as ToolRef[],
+    toolsProvided: row.toolsProvided,
+    model: row.model,
+    reasoningEffort: row.reasoningEffort as ReasoningEffort,
+    latencyMode: (row.latencyMode as LatencyMode | null | undefined) ?? "standard",
+    sandboxBackend: row.sandboxBackend as SandboxBackend,
+    sandboxOs: (row.sandboxOs as SandboxOs | null) ?? null,
+    metadata: row.metadata,
+    version: row.version,
+    executionGeneration: row.executionGeneration,
+    activeAttemptId: row.activeAttemptId,
+    lineage: row.lineage,
+    initiator: initiatorFromStorage(
+      row.initiatorKind,
+      row.initiatorSubjectId,
+      row.initiatorContext ?? {},
+    ),
+    initiatorContext: row.initiatorContext ?? {},
+    personalConnections,
+    cancelledBy: row.cancelledBy,
+    cancelReason: row.cancelReason,
+    startedAt: row.startedAt ? row.startedAt.toISOString() : null,
+    finishedAt: row.finishedAt ? row.finishedAt.toISOString() : null,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
 export type AgentInternalUpdateCommandResult = {
   receipt: SessionCommandReceiptRow;
   updateId: string;
@@ -149,6 +237,43 @@ async function personalConnectionDelegationsForAgentActor(
   return parsed.data.map((delegation) => ({ ...delegation }));
 }
 
+async function xaiAuthorityForAgentActor(
+  db: Database,
+  workspaceId: string,
+  actor: Extract<SessionCommandActor, { type: "agent_attempt" }>,
+): Promise<{
+  snapshot: ReturnType<typeof XaiProviderAccountAuthoritySnapshotV1.parse>;
+  subjectId: string | null;
+}> {
+  const [row] = await db
+    .select({
+      snapshot: schema.sessionTurns.xaiProviderAccountAuthoritySnapshot,
+      initiatingHumanSubjectId: schema.sessionTurns.initiatingHumanSubjectId,
+      initiatorKind: schema.sessionTurns.initiatorKind,
+      initiatorSubjectId: schema.sessionTurns.initiatorSubjectId,
+    })
+    .from(schema.sessionTurns)
+    .where(
+      and(
+        eq(schema.sessionTurns.workspaceId, workspaceId),
+        eq(schema.sessionTurns.sessionId, actor.sessionId),
+        eq(schema.sessionTurns.id, actor.turnId),
+      ),
+    )
+    .limit(1);
+  if (!row) {
+    throw new SessionControlInvariantError(
+      `Agent xAI authority turn not found: ${actor.sessionId}/${actor.turnId}`,
+    );
+  }
+  return {
+    snapshot: XaiProviderAccountAuthoritySnapshotV1.parse(row.snapshot),
+    subjectId:
+      row.initiatingHumanSubjectId ??
+      (row.initiatorKind === "subject" ? row.initiatorSubjectId : null),
+  };
+}
+
 async function lockSession(
   db: Database,
   workspaceId: string,
@@ -260,6 +385,12 @@ export async function supersedeSessionCurrentDirectionInTransaction(
   }
 
   const now = new Date();
+  await cancelTurnInteractionInterventionsInTransaction(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    sessionId: input.sessionId,
+    turnId: current.id,
+  });
   const closedTools = await closePendingSessionToolCallsInTransaction(db, {
     accountId: input.accountId,
     workspaceId: input.workspaceId,
@@ -308,7 +439,10 @@ export async function supersedeSessionCurrentDirectionInTransaction(
             turnId: current.id,
             turnGeneration: current.executionGeneration,
             turnAssociation: "current",
-            payload: { requestId: request.id, response: { outcome: "cancelled" } },
+            payload: {
+              requestId: request.id,
+              response: { outcome: "cancelled" },
+            },
             occurredAt: now,
           })),
           "payload",
@@ -370,6 +504,17 @@ export async function supersedeSessionCurrentDirectionInTransaction(
           eq(schema.codexCapacityWaiters.status, "waiting"),
         ),
       );
+    await db
+      .update(schema.xaiCapacityWaiters)
+      .set({ status: "superseded", lastWakeReason: "steer", updatedAt: now })
+      .where(
+        and(
+          eq(schema.xaiCapacityWaiters.workspaceId, input.workspaceId),
+          eq(schema.xaiCapacityWaiters.sessionId, input.sessionId),
+          eq(schema.xaiCapacityWaiters.blockedTurnId, current.id),
+          eq(schema.xaiCapacityWaiters.status, "waiting"),
+        ),
+      );
   }
   return {
     interruptionCount: 0,
@@ -414,7 +559,7 @@ async function loadQueuedTurns(
 }
 
 async function normalizeQueuePositions(
-  db: Database,
+  db: SessionActivityDatabase,
   workspaceId: string,
   sessionId: string,
   orderedIds: string[],
@@ -446,7 +591,19 @@ async function normalizeQueuePositions(
 }
 
 function draftIsNonEmpty(draft: ComposerDraftRow): boolean {
-  return draft.text.length > 0 || draft.resources.length > 0 || draft.sourceTurnId !== null;
+  return (
+    draft.text.length > 0 ||
+    DraftTimelineAnnotations.parse(draft.annotations).length > 0 ||
+    draft.resources.length > 0 ||
+    draft.sourceTurnId !== null
+  );
+}
+
+function draftAnnotationsFromTurn(value: unknown): DraftTimelineAnnotation[] {
+  return TimelineAnnotations.parse(value).map(({ ordinal: _ordinal, ...annotation }) => ({
+    ...annotation,
+    source: { ...annotation.source },
+  }));
 }
 
 function withCanonicalResourceMountPaths(resources: readonly unknown[]): unknown[] {
@@ -503,6 +660,7 @@ export async function saveComposerDraftInTransaction(
     subjectId: string;
     expectedRevision: number;
     text: string;
+    annotations?: DraftTimelineAnnotation[];
     resources: ResourceRef[];
     model: string;
     reasoningEffort: ReasoningEffort;
@@ -534,6 +692,7 @@ export async function saveComposerDraftInTransaction(
     subjectId: input.subjectId,
     revision,
     text: input.text,
+    annotations: DraftTimelineAnnotations.parse(input.annotations ?? []),
     resources: withCanonicalResourceMountPaths(input.resources),
     tools: [],
     toolsProvided: false,
@@ -559,7 +718,7 @@ export async function saveComposerDraftInTransaction(
 }
 
 export async function moveQueuedTurnInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -695,7 +854,7 @@ export async function moveQueuedTurnInTransaction(
 }
 
 export async function deleteSessionQueueItemInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -826,7 +985,7 @@ export async function deleteSessionQueueItemInTransaction(
 }
 
 export async function editQueuedTurnInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -919,6 +1078,7 @@ export async function editQueuedTurnInTransaction(
     subjectId: input.subjectId,
     revision: nextDraftRevision,
     text: turn.prompt,
+    annotations: draftAnnotationsFromTurn(turn.annotations),
     resources: withCanonicalResourceMountPaths(turn.resources),
     tools: [],
     toolsProvided: false,
@@ -1007,7 +1167,7 @@ export async function editQueuedTurnInTransaction(
 }
 
 export async function steerQueuedTurnInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -1240,7 +1400,7 @@ export async function steerQueuedTurnInTransaction(
 }
 
 export async function submitHumanPromptInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -1253,6 +1413,7 @@ export async function submitHumanPromptInTransaction(
     controlEtag?: string | null;
     expectedDraftRevision?: number | null;
     text: string;
+    annotations?: TimelineAnnotation[];
     turnInstructions?: string | null;
     resources: ResourceRef[];
     model?: string | null;
@@ -1270,6 +1431,8 @@ export async function submitHumanPromptInTransaction(
       context: string;
     };
     source: "user" | "api";
+    /** Record the admitted run's durable usage fact in this transaction. */
+    recordAgentRunUsage?: boolean;
     personalConnectionDelegations?: McpPersonalConnectionDelegation[];
     mcpCredentialUpdates?: Array<{
       id: string;
@@ -1277,6 +1440,7 @@ export async function submitHumanPromptInTransaction(
     }>;
   },
 ): Promise<SubmitHumanPromptResult> {
+  const annotations = TimelineAnnotations.parse(input.annotations ?? []);
   const workspaceControl = await lockWorkspaceInferenceControl(db, input.workspaceId, "update");
   await lockSessionEventWriteRows(db, {
     workspaceId: input.workspaceId,
@@ -1293,6 +1457,7 @@ export async function submitHumanPromptInTransaction(
     controlEtag: input.controlEtag ?? null,
     expectedDraftRevision: input.expectedDraftRevision ?? null,
     text: input.text,
+    annotations,
     turnInstructions: input.turnInstructions ?? null,
     resources: withCanonicalResourceMountPaths(input.resources),
     model: input.model ?? null,
@@ -1332,9 +1497,39 @@ export async function submitHumanPromptInTransaction(
     if (!turnId || !acceptedEventId || wakeRevision < 1) {
       throw new SessionControlInvariantError("Replayed prompt receipt is incomplete");
     }
+    const replayEvents = await db
+      .select()
+      .from(schema.sessionEvents)
+      .where(
+        and(
+          eq(schema.sessionEvents.workspaceId, input.workspaceId),
+          eq(schema.sessionEvents.sessionId, input.sessionId),
+          inArray(schema.sessionEvents.id, eventIds),
+        ),
+      )
+      .orderBy(asc(schema.sessionEvents.sequence));
+    const [replayTurn] = await db
+      .select()
+      .from(schema.sessionTurns)
+      .where(
+        and(
+          eq(schema.sessionTurns.workspaceId, input.workspaceId),
+          eq(schema.sessionTurns.sessionId, input.sessionId),
+          eq(schema.sessionTurns.id, turnId),
+        ),
+      )
+      .limit(1);
+    const events = replayEvents.map(mapSubmittedPromptEvent);
+    const accepted = events.find((event) => event.id === acceptedEventId);
+    if (!accepted || !replayTurn || events.length !== eventIds.length) {
+      throw new SessionControlInvariantError("Replayed prompt rows are incomplete");
+    }
     return {
       receipt: reserved.receipt,
       queueVersion: Number(reserved.receipt.appliedQueueVersion),
+      accepted,
+      events,
+      turn: mapSubmittedPromptTurn(replayTurn),
       acceptedEventId,
       eventIds,
       turnId,
@@ -1404,6 +1599,7 @@ export async function submitHumanPromptInTransaction(
       draft &&
       canonicalSessionCommandHash({
         text: draft.text,
+        annotations: DraftTimelineAnnotations.parse(draft.annotations),
         resources: withCanonicalResourceMountPaths(draft.resources),
         model: draft.model,
         reasoningEffort: draft.reasoningEffort,
@@ -1411,6 +1607,7 @@ export async function submitHumanPromptInTransaction(
       }) !==
         canonicalSessionCommandHash({
           text: input.text,
+          annotations: annotations.map(({ ordinal: _ordinal, ...annotation }) => annotation),
           resources: withCanonicalResourceMountPaths(input.resources),
           model: input.model ?? session.model,
           reasoningEffort: input.reasoningEffort ?? input.reasoningEffortFallback,
@@ -1516,6 +1713,15 @@ export async function submitHumanPromptInTransaction(
       input.subjectLabel,
     );
   }
+  const xaiProviderAccountAuthoritySnapshot = editedSourceTurn
+    ? XaiProviderAccountAuthoritySnapshotV1.parse(
+        editedSourceTurn.xaiProviderAccountAuthoritySnapshot,
+      )
+    : input.actor.type === "human"
+      ? await resolveXaiProviderAccountAuthoritySnapshotForAcceptanceInTransaction(db, {
+          workspaceId: input.workspaceId,
+        })
+      : WORKSPACE_XAI_PROVIDER_ACCOUNT_AUTHORITY_SNAPSHOT_V1;
   const acceptedEventId = crypto.randomUUID();
   const turnId = crypto.randomUUID();
   const workflowId = session.temporalWorkflowId ?? `session-${session.id}`;
@@ -1531,6 +1737,7 @@ export async function submitHumanPromptInTransaction(
       clientEventId: input.operationKey,
       payload: {
         text: input.messagePresentation?.text ?? input.text,
+        ...(annotations.length > 0 ? { annotations } : {}),
         ...(input.messagePresentation
           ? {
               presentation: {
@@ -1565,6 +1772,7 @@ export async function submitHumanPromptInTransaction(
           source: input.source,
           position: input.delivery === "steer" ? 0 : existingQueued.length + 1,
           prompt: input.text,
+          annotations,
           turnInstructions:
             editedSourceTurnInstructions !== undefined
               ? editedSourceTurnInstructions
@@ -1592,6 +1800,7 @@ export async function submitHumanPromptInTransaction(
           personalConnectionDelegations: editedSourceTurn
             ? editedSourceTurn.personalConnectionDelegations
             : (input.personalConnectionDelegations ?? []),
+          xaiProviderAccountAuthoritySnapshot,
           createdAt: now,
           updatedAt: now,
         },
@@ -1601,6 +1810,7 @@ export async function submitHumanPromptInTransaction(
     )
     .returning();
   if (!turn) throw new SessionControlInvariantError("Prompt turn was not inserted");
+  let committedTurn = turn;
   eventValues.push({
     accountId: input.accountId,
     workspaceId: input.workspaceId,
@@ -1651,7 +1861,7 @@ export async function submitHumanPromptInTransaction(
   // settlement has already cleared sessions.active_turn_id. Do not infer this
   // state from a local request spinner or queue position.
   if (input.delivery === "steer") {
-    await db
+    const [updatedTurn] = await db
       .update(schema.sessionTurns)
       .set({
         metadata: {
@@ -1669,7 +1879,12 @@ export async function submitHumanPromptInTransaction(
           eq(schema.sessionTurns.sessionId, input.sessionId),
           eq(schema.sessionTurns.id, turnId),
         ),
-      );
+      )
+      .returning();
+    if (!updatedTurn) {
+      throw new SessionControlInvariantError("Steer prompt turn metadata was not updated");
+    }
+    committedTurn = updatedTurn;
   }
   if (supersession.replacedTurn) {
     const current = supersession.replacedTurn;
@@ -1749,7 +1964,7 @@ export async function submitHumanPromptInTransaction(
       text: renderRealtimeHumanInputContext({
         delivery: input.delivery,
         routing: realtimeRouting,
-        text: input.text,
+        text: renderTimelineAnnotationsForModel(input.text, annotations),
       }),
       payload: {
         delivery: input.delivery,
@@ -1811,6 +2026,27 @@ export async function submitHumanPromptInTransaction(
       "metadataCodecVersion",
     ),
   );
+  if (input.recordAgentRunUsage) {
+    await db
+      .insert(schema.usageEvents)
+      .values({
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        subjectId: input.subjectId,
+        eventType: "agent_run.created",
+        quantity: 1,
+        unit: "run",
+        sourceResourceType: "session_turn",
+        sourceResourceId: turnId,
+        sessionId: input.sessionId,
+        turnId,
+        ...initiatorColumns(frozenInitiator),
+        origin: input.source,
+        idempotencyKey: `agent_run.created:${input.workspaceId}:${turnId}`,
+        occurredAt: now,
+      })
+      .onConflictDoNothing({ target: schema.usageEvents.idempotencyKey });
+  }
   const eventIds = eventRows.map((event) => event.id);
   const receipt = await updateSessionCommandReceiptResult(db, reserved.receipt.id, {
     controlRevision: resumed.revision,
@@ -1832,9 +2068,17 @@ export async function submitHumanPromptInTransaction(
         : {}),
     },
   });
+  const events = eventRows.map(mapSubmittedPromptEvent);
+  const accepted = events.find((event) => event.id === acceptedEventId);
+  if (!accepted) {
+    throw new SessionControlInvariantError("Inserted user.message event is missing");
+  }
   return {
     receipt,
     queueVersion,
+    accepted,
+    events,
+    turn: mapSubmittedPromptTurn(committedTurn),
     acceptedEventId,
     eventIds,
     turnId,
@@ -1846,7 +2090,7 @@ export async function submitHumanPromptInTransaction(
 }
 
 export async function sendAgentMessageInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -1910,6 +2154,7 @@ export async function sendAgentMessageInTransaction(
     input.workspaceId,
     input.actor,
   );
+  const xaiAuthority = await xaiAuthorityForAgentActor(db, input.workspaceId, input.actor);
   const session = await lockSession(db, input.workspaceId, input.targetSessionId);
   if (session.status === "cancelled") {
     throw new QueueCommandConflictError(
@@ -1951,8 +2196,10 @@ export async function sendAgentMessageInTransaction(
               callerTurnId: input.actor.turnId,
               callerAttemptId: input.actor.attemptId,
               callerExecutionGeneration: input.actor.executionGeneration,
+              ...(xaiAuthority.subjectId ? { xaiAuthoritySubjectId: xaiAuthority.subjectId } : {}),
             },
             personalConnectionDelegations,
+            xaiProviderAccountAuthoritySnapshot: xaiAuthority.snapshot,
             state: "pending",
           },
           "summary",
@@ -2050,7 +2297,7 @@ export async function sendAgentMessageInTransaction(
 }
 
 export async function steerAgentSessionInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;
@@ -2117,6 +2364,7 @@ export async function steerAgentSessionInTransaction(
     input.workspaceId,
     input.actor,
   );
+  const xaiAuthority = await xaiAuthorityForAgentActor(db, input.workspaceId, input.actor);
   const resumed = await autoResumeSessionBranchInTransaction(db, {
     workspaceId: input.workspaceId,
     sessionId: input.targetSessionId,
@@ -2178,8 +2426,10 @@ export async function steerAgentSessionInTransaction(
               callerTurnId: input.actor.turnId,
               callerAttemptId: input.actor.attemptId,
               callerExecutionGeneration: input.actor.executionGeneration,
+              ...(xaiAuthority.subjectId ? { xaiAuthoritySubjectId: xaiAuthority.subjectId } : {}),
             },
             personalConnectionDelegations,
+            xaiProviderAccountAuthoritySnapshot: xaiAuthority.snapshot,
             state: "pending",
           },
           "summary",

package/src/session-realtime-context.ts

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import { ReasoningEffort } from "@opengeni/contracts";
 import { and, asc, desc, eq, inArray, isNull, sql } from "drizzle-orm";
 
-import type { Database } from "./database";
+import type { Database, SessionActivityDatabase } from "./database";
 import { fromPostgresLosslessJson, fromPostgresLosslessText } from "./lossless-json";
 import * as schema from "./schema";
 import { submitHumanPromptInTransaction } from "./session-queue-commands";
@@ -178,7 +178,7 @@ function mapProjection(
  * delegation into the same canonical Steer-or-start path used by a human.
  */
 export async function flushSessionRealtimeTranscriptTailInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: {
     accountId: string;
     workspaceId: string;

package/src/session-realtime-ledger.ts

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import { LatencyMode, ReasoningEffort, type SessionRealtimeMode } from "@opengeni/contracts";
 import { and, asc, desc, eq, inArray, isNull, or, sql } from "drizzle-orm";
 
-import type { Database } from "./database";
+import type { Database, SessionActivityDatabase } from "./database";
 import {
   fromPostgresLosslessJson,
   fromPostgresLosslessText,
@@ -1075,7 +1075,7 @@ async function appendInvalidDelegationFailure(
 }
 
 async function admitRealtimeDelegationInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: Pick<
     SyncSessionRealtimeLedgerInput,
     "workspaceId" | "sessionId" | "realtimeId" | "connectionEpoch" | "ownerSubjectId"
@@ -1268,7 +1268,7 @@ function assertProviderAckSequences(values: number[] | undefined, maximum: numbe
 }
 
 export async function syncSessionRealtimeLedgerInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: SyncSessionRealtimeLedgerInput,
   hooks: SyncSessionRealtimeLedgerHooks = {},
 ): Promise<SyncSessionRealtimeLedgerResult> {

package/src/session-realtime.ts

@@ -8,7 +8,7 @@ import type {
 } from "@opengeni/contracts";
 import { and, asc, eq, gt, inArray, isNull, or } from "drizzle-orm";
 
-import type { Database } from "./database";
+import type { Database, SessionActivityDatabase } from "./database";
 import { LOSSLESS_CONTENT_CODEC_VERSION } from "./lossless-json";
 import { flushSessionRealtimeTranscriptTailInTransaction } from "./session-realtime-context";
 import {
@@ -161,7 +161,7 @@ function assertOwner(
 }
 
 async function appendRealtimeLifecycleEvent(
-  db: Database,
+  db: SessionActivityDatabase,
   session: SessionRow,
   sequence: number,
   type: Extract<SessionEventType, "session.realtime.started" | "session.realtime.ended">,
@@ -259,7 +259,7 @@ async function registerNormalModeWake(db: Database, session: SessionRow, reason:
 }
 
 async function endWithEvent(
-  db: Database,
+  db: SessionActivityDatabase,
   session: SessionRow,
   row: RealtimeRow,
   reason: SessionRealtimeEndReason,
@@ -352,7 +352,7 @@ function assertRealtimeAdmission(session: SessionRow): void {
 }
 
 export async function beginSessionRealtimeInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: BeginSessionRealtimeInput,
 ): Promise<SessionRealtimeMutationResult> {
   const now = input.now ?? new Date();
@@ -553,7 +553,7 @@ export async function assertSessionRealtimeOwnerInTransaction(
 }
 
 export async function renewSessionRealtimeInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: RenewSessionRealtimeInput,
 ): Promise<RenewSessionRealtimeResult> {
   const now = input.now ?? new Date();
@@ -616,7 +616,7 @@ export async function renewSessionRealtimeInTransaction(
 }
 
 export async function endSessionRealtimeInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   input: EndSessionRealtimeInput,
 ): Promise<SessionRealtimeMutationResult> {
   const now = input.now ?? new Date();
@@ -649,7 +649,7 @@ export async function endSessionRealtimeInTransaction(
 
 /** Lazily settle an expired voice lease under the canonical session lock. */
 export async function settleExpiredSessionRealtimeInTransaction(
-  db: Database,
+  db: SessionActivityDatabase,
   session: SessionRow,
   now = new Date(),
 ): Promise<SessionRow> {