@opengeni/db 3.6.0 → 3.7.4-canary.0

package/src/session-control.ts

@@ -104,6 +104,18 @@ export type EffectiveSessionControl = {
   } | null;
 };
 
+/**
+ * The bounded control projection required by a locked activity-write fence.
+ * Settlement and background-command summaries are read-model concerns and must
+ * not extend the session-event critical section when admission only needs the
+ * effective run state and blocker scope.
+ */
+export type SessionWriteAdmissionControl = {
+  state: EffectiveControlState;
+  controlVersion: number;
+  primaryBlockerKind: EffectiveControlBlocker["kind"] | null;
+};
+
 type SettlementAttemptCounts = {
   attemptCount: number;
   interruptionPendingCount: number;
@@ -627,6 +639,13 @@ export type SessionEventWriteLockInput = {
   controlLock: WorkspaceControlLockMode | "already_locked" | "none";
   /** Used only when a staged caller already established the workspace prefix. */
   workspaceLock?: "key_share" | "already_locked";
+  /**
+   * Semantic writers retain FOR NO KEY UPDATE. Cursor-authoritative raw-only
+   * appends need only the FK-compatible identity hold; KEY SHARE is compatible
+   * with semantic NO KEY UPDATE and therefore removes the wide session row as
+   * their serialization mutex without inverting the rolling lock order.
+   */
+  sessionLock?: "no_key_update" | "key_share";
   sessionIds?: string[];
   turnIds?: string[];
   attemptIds?: string[];
@@ -636,6 +655,7 @@ export type SessionEventWriteLocks = {
   control: WorkspaceControlRow | null;
   workspace: typeof schema.workspaces.$inferSelect | null;
   sessions: Array<typeof schema.sessions.$inferSelect>;
+  cursors: Array<typeof schema.sessionEventCursors.$inferSelect>;
   turns: Array<typeof schema.sessionTurns.$inferSelect>;
   attempts: Array<typeof schema.sessionTurnAttempts.$inferSelect>;
 };
@@ -646,7 +666,8 @@ export type SessionEventWriteLocks = {
  *   workspace-control advisory lock + workspace_inference_controls row
  *     (when control-aware; see `lockWorkspaceInferenceControl`)
  *     -> actual workspaces row FOR KEY SHARE
- *     -> session rows FOR NO KEY UPDATE, UUID ordered
+ *     -> session rows FOR NO KEY UPDATE (semantic) or KEY SHARE (raw), UUID ordered
+ *     -> session event cursor rows FOR UPDATE, UUID ordered
  *     -> exact turn rows FOR UPDATE, UUID ordered
  *     -> exact attempt rows FOR UPDATE, UUID ordered
  *
@@ -661,10 +682,12 @@ export type SessionEventWriteLocks = {
  * `FOR UPDATE` lock serialized unrelated sessions and inverted the activity
  * path's session -> implicit workspace-FK edge.
  *
- * `FOR NO KEY UPDATE` is equally deliberate for sessions. Session primary and
- * composite identity keys are immutable, so writers need to exclude only concurrent
- * non-key mutation. Keeping FK `FOR KEY SHARE` checks compatible prevents the
- * activity finalizer's workspace counter from participating in a lock cycle.
+ * `FOR NO KEY UPDATE` is equally deliberate for semantic session writers.
+ * Cursor-authoritative raw-only writers use `FOR KEY SHARE`: it preserves the
+ * session identity against deletion while remaining compatible with semantic
+ * `FOR NO KEY UPDATE`. Keeping this rolling session-before-cursor order avoids
+ * an inversion with old binaries and quiescent cascade deletion; the compact
+ * cursor row, not the wide session row, is the raw ordering mutex.
  *
  * Complex lifecycle transactions may acquire allocator/control locks before
  * this helper and may discover exact turn IDs only after locking the session.
@@ -698,7 +721,8 @@ export async function lockSessionEventWriteRows(
   }
 
   const sessionIds = [...new Set(input.sessionIds ?? [])].sort();
-  const sessions =
+  const sessionLock = input.sessionLock ?? "no_key_update";
+  let sessions =
     sessionIds.length > 0
       ? await db
           .select()
@@ -710,8 +734,72 @@ export async function lockSessionEventWriteRows(
             ),
           )
           .orderBy(schema.sessions.id)
-          .for("no key update")
+          .for(sessionLock === "key_share" ? "key share" : "no key update")
+      : [];
+
+  const cursors =
+    sessions.length > 0
+      ? await db
+          .select()
+          .from(schema.sessionEventCursors)
+          .where(
+            and(
+              eq(schema.sessionEventCursors.workspaceId, input.workspaceId),
+              inArray(
+                schema.sessionEventCursors.sessionId,
+                sessions.map((session) => session.id),
+              ),
+            ),
+          )
+          .orderBy(schema.sessionEventCursors.sessionId)
+          .for("update")
       : [];
+  if (cursors.length !== sessions.length) {
+    throw new SessionControlInvariantError(
+      `Session event cursor lock set was incomplete for workspace ${input.workspaceId}`,
+    );
+  }
+  if (sessionLock === "key_share" && sessions.length > 0) {
+    // KEY SHARE is intentionally compatible with a semantic writer's NO KEY
+    // UPDATE. If that writer reached the cursor first it may have committed a
+    // control/authority/session-state change after our initial identity read.
+    // Re-read only after owning the cursor so the attempt fence evaluates the
+    // latest committed session state while later semantic writers wait here.
+    sessions = await db
+      .select()
+      .from(schema.sessions)
+      .where(
+        and(
+          eq(schema.sessions.workspaceId, input.workspaceId),
+          inArray(schema.sessions.id, sessionIds),
+        ),
+      )
+      .orderBy(schema.sessions.id)
+      .for("key share");
+  }
+  const canonicalSessions = sessions.map((session, index) => {
+    const cursor = cursors[index]!;
+    if (
+      cursor.sessionId !== session.id ||
+      cursor.accountId !== session.accountId ||
+      cursor.workspaceId !== session.workspaceId
+    ) {
+      throw new SessionControlInvariantError(
+        `Session event cursor identity failed for session ${session.id}`,
+      );
+    }
+    // The cursor is the allocation authority. The wide session column remains
+    // a rolling compatibility/read projection until every reader is cut over.
+    // It may lag after the later pure-append activation, but it must never lead
+    // the durable cursor or an old writer could have committed an unverified
+    // sequence.
+    if (cursor.lastSequence < session.lastSequence) {
+      throw new SessionControlInvariantError(
+        `Session event cursor is behind session projection for session ${session.id}`,
+      );
+    }
+    return { ...session, lastSequence: cursor.lastSequence };
+  });
 
   const turnIds = [...new Set(input.turnIds ?? [])].sort();
   const turns =
@@ -745,7 +833,7 @@ export async function lockSessionEventWriteRows(
           .for("update")
       : [];
 
-  return { control, workspace, sessions, turns, attempts };
+  return { control, workspace, sessions: canonicalSessions, cursors, turns, attempts };
 }
 
 export async function registerSessionTurnAttemptClaim(
@@ -1337,6 +1425,10 @@ async function settlementAttemptCounts(
   workspaceId: string,
   sessionIds: string[],
 ): Promise<Map<string, SettlementAttemptCounts>> {
+  // Drive the projection from the requested targets through the indexed
+  // parent_session_id edge. The inverse plan scanned every interruption in a
+  // workspace before walking upward, making one session read proportional to
+  // a high-volume orchestrator workspace's entire interruption history.
   const rows = await db.execute<{
     sessionId: string;
     attemptCount: number | string;
@@ -1344,9 +1436,24 @@ async function settlementAttemptCounts(
     quiescencePendingCount: number | string;
   }>(sql`
     with recursive targets(id) as (values ${targetValues(sessionIds)}),
-    interruptions as (
+    descendant_sessions(target_id, session_id, depth, path) as (
+      select target.id, target.id, 0::integer, array[target.id]::uuid[]
+      from targets target
+      union all
+      select
+        descendant.target_id,
+        child.id,
+        descendant.depth + 1,
+        descendant.path || child.id
+      from descendant_sessions descendant
+      join ${schema.sessions} child
+        on child.workspace_id = ${workspaceId}
+       and child.parent_session_id = descendant.session_id
+      where not child.id = any(descendant.path)
+        and descendant.depth < ${SESSION_ANCESTRY_LIMIT}
+    ), interruptions as (
       select
-        interruption.session_id,
+        descendant.target_id,
         interruption.attempt_id,
         bool_or(interruption.state in ('pending', 'delivered', 'acknowledged'))
           as interruption_pending,
@@ -1354,62 +1461,31 @@ async function settlementAttemptCounts(
           interruption.state in ('settled', 'rejected_stale')
           and attempt.quiesced_at is null
         ) as quiescence_pending
-      from ${schema.sessionAttemptInterruptions} interruption
+      from descendant_sessions descendant
+      join ${schema.sessionAttemptInterruptions} interruption
+        on interruption.workspace_id = ${workspaceId}
+       and interruption.session_id = descendant.session_id
       join ${schema.sessionTurnAttempts} attempt
         on attempt.workspace_id = interruption.workspace_id
        and attempt.id = interruption.attempt_id
-      where interruption.workspace_id = ${workspaceId}
-        and (
+      where (
           interruption.state in ('pending', 'delivered', 'acknowledged')
           or (
             interruption.state in ('settled', 'rejected_stale')
             and attempt.quiesced_at is null
           )
         )
-      group by interruption.session_id, interruption.attempt_id
-    ), interruption_ancestry(
-      session_id,
-      ancestor_id,
-      attempt_id,
-      interruption_pending,
-      quiescence_pending,
-      depth,
-      path
-    ) as (
-      select
-        interruption.session_id,
-        interruption.session_id,
-        interruption.attempt_id,
-        interruption.interruption_pending,
-        interruption.quiescence_pending,
-        0::integer,
-        array[interruption.session_id]::uuid[]
-      from interruptions interruption
-      union all
-      select
-        ancestry.session_id,
-        current.parent_session_id,
-        ancestry.attempt_id,
-        ancestry.interruption_pending,
-        ancestry.quiescence_pending,
-        ancestry.depth + 1,
-        ancestry.path || current.parent_session_id
-      from interruption_ancestry ancestry
-      join ${schema.sessions} current
-        on current.workspace_id = ${workspaceId} and current.id = ancestry.ancestor_id
-      where current.parent_session_id is not null
-        and not current.parent_session_id = any(ancestry.path)
-        and ancestry.depth < ${SESSION_ANCESTRY_LIMIT}
+      group by descendant.target_id, interruption.attempt_id
     )
     select
       target.id as "sessionId",
-      count(distinct ancestry.attempt_id)::integer as "attemptCount",
-      count(distinct ancestry.attempt_id)
-        filter (where ancestry.interruption_pending)::integer as "interruptionPendingCount",
-      count(distinct ancestry.attempt_id)
-        filter (where ancestry.quiescence_pending)::integer as "quiescencePendingCount"
+      count(interruption.attempt_id)::integer as "attemptCount",
+      count(interruption.attempt_id)
+        filter (where interruption.interruption_pending)::integer as "interruptionPendingCount",
+      count(interruption.attempt_id)
+        filter (where interruption.quiescence_pending)::integer as "quiescencePendingCount"
     from targets target
-    join interruption_ancestry ancestry on ancestry.ancestor_id = target.id
+    join interruptions interruption on interruption.target_id = target.id
     group by target.id
   `);
   return new Map(
@@ -1500,6 +1576,46 @@ export async function evaluateSessionControls(
   return result;
 }
 
+/**
+ * Evaluate only the control facts needed to admit an already locked session
+ * write. The workspace-control row must be reused when the caller established
+ * the canonical prefix before session/turn/attempt locks.
+ *
+ * Deliberately omit settlementAttemptCounts and
+ * stoppingBackgroundCommandCounts: those recursive summaries do not affect
+ * effective pause state and their results are discarded by the write fence.
+ */
+export async function evaluateSessionWriteAdmissionControl(
+  db: Database,
+  workspaceId: string,
+  sessionId: string,
+  options: {
+    lock?: WorkspaceControlLockMode;
+    workspaceControl?: WorkspaceControlRow | undefined;
+  } = {},
+): Promise<SessionWriteAdmissionControl> {
+  if (options.workspaceControl && options.workspaceControl.workspaceId !== workspaceId) {
+    throw new SessionControlInvariantError(
+      `Locked workspace control ${options.workspaceControl.workspaceId} does not match ${workspaceId}`,
+    );
+  }
+  const workspace =
+    options.workspaceControl ??
+    (await lockWorkspaceInferenceControl(db, workspaceId, options.lock ?? "share"));
+  const projected = projectEffectiveControl(
+    workspace,
+    sessionId,
+    await loadTargetAncestryRows(db, workspaceId, [sessionId]),
+    NO_SETTLEMENT_ATTEMPTS,
+    0,
+  );
+  return {
+    state: projected.state,
+    controlVersion: projected.controlVersion,
+    primaryBlockerKind: projected.primaryBlocker?.kind ?? null,
+  };
+}
+
 type SessionDiscoveryControlRow = {
   targetId: string;
   ancestryCount: number | string;
@@ -1768,6 +1884,174 @@ async function findCommandReceipt(
   return rows[0] ?? null;
 }
 
+export type SessionPromptCommandAction = "prompt.send" | "prompt.steer";
+
+async function findPromptCommandReceipts(
+  db: Database,
+  input: {
+    workspaceId: string;
+    actor: SessionCommandActor;
+    operationKey: string;
+    lock?: "none" | "update";
+  },
+): Promise<SessionCommandReceiptRow[]> {
+  const actorSubjectId = input.actor.type === "agent_attempt" ? null : input.actor.subjectId;
+  const actorAttemptId = input.actor.type === "agent_attempt" ? input.actor.attemptId : null;
+  const query = db
+    .select()
+    .from(schema.sessionCommandReceipts)
+    .where(
+      and(
+        eq(schema.sessionCommandReceipts.workspaceId, input.workspaceId),
+        eq(schema.sessionCommandReceipts.actorType, input.actor.type),
+        sql`${schema.sessionCommandReceipts.actorSubjectId} is not distinct from ${actorSubjectId}`,
+        sql`${schema.sessionCommandReceipts.actorAttemptId} is not distinct from ${actorAttemptId}::uuid`,
+        inArray(schema.sessionCommandReceipts.action, ["prompt.send", "prompt.steer"]),
+        eq(schema.sessionCommandReceipts.operationKey, input.operationKey),
+      ),
+    );
+  const rows = input.lock === "update" ? await query.for("update") : await query;
+  return rows;
+}
+
+function fingerprintedPromptCommandReceipt(
+  receipts: readonly SessionCommandReceiptRow[],
+): SessionCommandReceiptRow | null {
+  const fingerprinted = receipts.filter(
+    (receipt) => typeof receipt.result.boundaryRequestHash === "string",
+  );
+  if (fingerprinted.length > 1) {
+    throw new SessionControlInvariantError(
+      "Prompt operation key resolved to multiple fingerprinted receipts",
+    );
+  }
+  return fingerprinted[0] ?? null;
+}
+
+function assertPromptCommandReceiptIdentity(
+  receipt: SessionCommandReceiptRow,
+  input: {
+    action: SessionPromptCommandAction;
+    targetSessionId: string;
+    boundaryRequestHash: string;
+  },
+): void {
+  if (
+    receipt.action !== input.action ||
+    receipt.targetSessionId !== input.targetSessionId ||
+    receipt.targetTurnId !== null ||
+    (typeof receipt.result.boundaryRequestHash === "string" &&
+      receipt.result.boundaryRequestHash !== input.boundaryRequestHash)
+  ) {
+    throw new SessionCommandIdempotencyError();
+  }
+}
+
+/**
+ * Prompt operation keys are actor-scoped across target sessions and across the
+ * Send/Steer action pair. The advisory lock closes the gap left by the legacy
+ * action/target-specific unique index without changing old receipt identities.
+ */
+export async function reserveSessionPromptCommandReceipt(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    actor: SessionCommandActor;
+    action: SessionPromptCommandAction;
+    targetSessionId: string;
+    operationKey: string;
+    canonicalRequestHash: string;
+    boundaryRequestHash: string;
+  },
+): Promise<{ receipt: SessionCommandReceiptRow; replay: boolean }> {
+  await lockSessionPromptCommandOperation(db, input);
+  const existingReceipts = await findPromptCommandReceipts(db, {
+    workspaceId: input.workspaceId,
+    actor: input.actor,
+    operationKey: input.operationKey,
+    lock: "update",
+  });
+  const fingerprinted = fingerprintedPromptCommandReceipt(existingReceipts);
+  if (fingerprinted) {
+    assertPromptCommandReceiptIdentity(fingerprinted, input);
+    return { receipt: fingerprinted, replay: true };
+  }
+  const legacyExact = existingReceipts.find(
+    (receipt) =>
+      receipt.action === input.action &&
+      receipt.targetSessionId === input.targetSessionId &&
+      receipt.targetTurnId === null,
+  );
+  if (legacyExact) {
+    if (legacyExact.canonicalRequestHash !== input.canonicalRequestHash) {
+      throw new SessionCommandIdempotencyError();
+    }
+    return { receipt: legacyExact, replay: true };
+  }
+  return await reserveSessionCommandReceipt(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    actor: input.actor,
+    action: input.action,
+    targetSessionId: input.targetSessionId,
+    targetTurnId: null,
+    operationKey: input.operationKey,
+    canonicalRequestHash: input.canonicalRequestHash,
+    ...(existingReceipts.length === 0
+      ? { initialResult: { boundaryRequestHash: input.boundaryRequestHash } }
+      : {}),
+  });
+}
+
+/** Serialize one actor-scoped prompt operation before replay or reservation. */
+export async function lockSessionPromptCommandOperation(
+  db: Database,
+  input: {
+    workspaceId: string;
+    actor: SessionCommandActor;
+    operationKey: string;
+  },
+): Promise<void> {
+  const actorIdentity =
+    input.actor.type === "agent_attempt"
+      ? `attempt:${input.actor.attemptId}`
+      : `${input.actor.type}:${input.actor.subjectId}`;
+  await db.execute(
+    sql`select pg_advisory_xact_lock(hashtextextended(${`session-prompt:${input.workspaceId}:${actorIdentity}:${input.operationKey}`}, 0))`,
+  );
+}
+
+/** Return only a fully committed exact prompt receipt with the new boundary fingerprint. */
+export async function getCompletedSessionPromptCommandReceipt(
+  db: Database,
+  input: {
+    workspaceId: string;
+    actor: SessionCommandActor;
+    action: SessionPromptCommandAction;
+    targetSessionId: string;
+    operationKey: string;
+    boundaryRequestHash: string;
+  },
+): Promise<SessionCommandReceiptRow | null> {
+  const receipt = fingerprintedPromptCommandReceipt(
+    await findPromptCommandReceipts(db, {
+      workspaceId: input.workspaceId,
+      actor: input.actor,
+      operationKey: input.operationKey,
+    }),
+  );
+  if (!receipt) return null;
+  assertPromptCommandReceiptIdentity(receipt, input);
+  if (
+    typeof receipt.result.boundaryRequestHash !== "string" ||
+    receipt.appliedQueueVersion === null
+  ) {
+    return null;
+  }
+  return receipt;
+}
+
 export async function reserveSessionCommandReceipt(
   db: Database,
   input: {
@@ -1780,6 +2064,7 @@ export async function reserveSessionCommandReceipt(
     operationKey: string;
     canonicalRequestHash: string;
     identityScope?: "actor" | "goal_operation";
+    initialResult?: Record<string, unknown>;
   },
 ): Promise<{ receipt: SessionCommandReceiptRow; replay: boolean }> {
   if (!input.operationKey.trim()) throw new Error("operationKey must not be empty");
@@ -1810,6 +2095,7 @@ export async function reserveSessionCommandReceipt(
       targetTurnId: input.targetTurnId,
       operationKey: input.operationKey,
       canonicalRequestHash: input.canonicalRequestHash,
+      result: input.initialResult ?? {},
     })
     .onConflictDoNothing()
     .returning();
@@ -3250,6 +3536,11 @@ export async function mutateSessionControlInTransaction(
     }
   }
 
+  const targetSession = locks.sessions.find((session) => session.id === input.sessionId);
+  if (!targetSession) {
+    throw new SessionControlInvariantError(`Session ${input.sessionId} disappeared`);
+  }
+
   const revision = nextRevision(workspace);
   await advanceWorkspaceRevision(db, input.workspaceId, revision);
   const updatedRows = await db
@@ -3290,10 +3581,7 @@ export async function mutateSessionControlInTransaction(
           : eq(schema.sessions.id, input.sessionId),
       ),
     )
-    .returning({
-      id: schema.sessions.id,
-      lastSequence: schema.sessions.lastSequence,
-    });
+    .returning({ id: schema.sessions.id });
   const updated = updatedRows.find((row) => row.id === input.sessionId);
   if (!updated) throw new SessionControlInvariantError(`Session ${input.sessionId} disappeared`);
 
@@ -3356,7 +3644,7 @@ export async function mutateSessionControlInTransaction(
           accountId: input.accountId,
           workspaceId: input.workspaceId,
           sessionId: input.sessionId,
-          sequence: updated.lastSequence + 1,
+          sequence: targetSession.lastSequence + 1,
           type:
             input.action === "pause" || input.action === "cancel"
               ? "session.control.paused"
@@ -3380,7 +3668,7 @@ export async function mutateSessionControlInTransaction(
     throw new SessionControlInvariantError("Session control event was not inserted");
   await db
     .update(schema.sessions)
-    .set({ lastSequence: updated.lastSequence + 1, updatedAt: new Date() })
+    .set({ lastSequence: targetSession.lastSequence + 1, updatedAt: new Date() })
     .where(eq(schema.sessions.id, input.sessionId));
   await db.insert(schema.auditEvents).values(
     withLosslessContentWriteVersion(