@opengeni/db 0.22.2 → 0.26.0

package/src/workspace-instruction-policies.ts

@@ -1,5 +1,10 @@
-import { createHash } from "node:crypto";
-import { WORKSPACE_INSTRUCTION_POLICY_CONTENT_MAX_CHARS } from "@opengeni/contracts";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  PreferenceRegistrySnapshot,
+  ResolvedWorkspaceInstructionPolicySnapshot,
+  WORKSPACE_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
+  WorkspaceInstructionPolicySnapshot,
+} from "@opengeni/contracts";
 import type {
   WorkspaceInstructionPolicyActivationEvent,
   WorkspaceInstructionPolicyActivationResponse,
@@ -13,14 +18,17 @@ import type {
   WorkspaceInstructionPolicyProvenanceSource,
   WorkspaceInstructionPolicyRevision,
   WorkspaceInstructionPolicyScope,
+  WorkspaceInstructionPolicySnapshotEntry,
   WorkspaceInstructionPolicyTarget,
 } from "@opengeni/contracts";
-import { and, asc, desc, eq, isNull, lt, type SQL } from "drizzle-orm";
+import { and, asc, desc, eq, inArray, isNull, lt, or, sql, type SQL } from "drizzle-orm";
 import type { Database } from "./index";
-import { withRlsContext, withWorkspaceRls } from "./index";
+import { withRlsContext, withWorkspaceRls, withWorkspaceSubjectRls } from "./index";
+import { nestedPostgresSqlState } from "./persistence-errors";
 import * as schema from "./schema";
 
-type DraftInput = WorkspaceInstructionPolicyTarget & {
+type DraftRequestInput = WorkspaceInstructionPolicyTarget & {
+  operationId: string;
   accountId: string;
   workspaceId: string;
   content: string;
@@ -30,10 +38,35 @@ type DraftInput = WorkspaceInstructionPolicyTarget & {
   createdBySubjectId: string;
 };
 
-type CallerDraftInput = Omit<DraftInput, "provenanceSource"> & {
+type DraftInput = DraftRequestInput & {
+  requestFingerprint: string;
+};
+
+type CallerDraftInput = Omit<DraftRequestInput, "operationId" | "provenanceSource"> & {
+  operationId?: string;
   provenanceSource: WorkspaceInstructionPolicyDraftProvenanceSource;
 };
 
+type ImportLegacyRequestInput = {
+  operationId: string;
+  accountId: string;
+  workspaceId: string;
+  createdBySubjectId: string;
+  supersedesRevisionId: string | null;
+};
+
+type ActiveRevisionInput = {
+  operationId: string;
+  accountId: string;
+  workspaceId: string;
+  targetRevisionId: string;
+  expectedCurrentRevisionId: string | null;
+  expectedActivationVersion?: number;
+  actorSubjectId: string;
+  reason: string;
+  type: WorkspaceInstructionPolicyActivationType;
+};
+
 export class WorkspaceInstructionPolicyConflictError extends Error {
   readonly name = "WorkspaceInstructionPolicyConflictError";
   readonly code = "WORKSPACE_INSTRUCTION_POLICY_CONFLICT";
@@ -43,6 +76,15 @@ export class WorkspaceInstructionPolicyConflictError extends Error {
   }
 }
 
+export class WorkspaceInstructionPolicyOperationReuseError extends Error {
+  readonly name = "WorkspaceInstructionPolicyOperationReuseError";
+  readonly code = "WORKSPACE_INSTRUCTION_POLICY_OPERATION_REUSED";
+
+  constructor() {
+    super("The workspace instruction-policy operation id was already used for another request");
+  }
+}
+
 export class WorkspaceInstructionPolicyNotFoundError extends Error {
   readonly name = "WorkspaceInstructionPolicyNotFoundError";
 
@@ -63,14 +105,244 @@ export class WorkspaceInstructionPolicyLegacyUnavailableError extends Error {
   }
 }
 
+export class WorkspaceInstructionPolicySnapshotAuthorityError extends Error {
+  readonly name = "WorkspaceInstructionPolicySnapshotAuthorityError";
+}
+
+export type WorkspaceInstructionPolicyAttemptClaims = {
+  accountId: string;
+  workspaceId: string;
+  sessionId: string;
+  turnId: string;
+  attemptId: string;
+  executionGeneration: number;
+};
+
+export type WorkspaceStateAcceptedAttemptGovernance = {
+  attemptId: string;
+  executionGeneration: number;
+  acceptedAt: string;
+  policySnapshot: WorkspaceInstructionPolicySnapshot | null;
+  preferenceSnapshot: {
+    id: string;
+    descriptorHash: string;
+    descriptors: Array<{
+      id: string;
+      revisionId: string;
+      contentHash: string;
+      activeVersion: number;
+      scope: "organization" | "workspace" | "user";
+    }>;
+    truncated: boolean;
+    createdAt: string;
+  } | null;
+};
+
 function contentHash(content: string): string {
   return createHash("sha256").update(content, "utf8").digest("hex");
 }
 
+type OperationFingerprintField = readonly [
+  name: string,
+  present: boolean,
+  value: string | number | null,
+];
+
+function hasOwnField(value: object, field: PropertyKey): boolean {
+  return Object.prototype.hasOwnProperty.call(value, field);
+}
+
+function operationRequestFingerprint(
+  operation: string,
+  fields: readonly OperationFingerprintField[],
+): string {
+  const canonicalRequest = JSON.stringify([
+    "workspace_instruction_policy_operation",
+    1,
+    operation,
+    fields,
+  ]);
+  return createHash("sha256").update(canonicalRequest, "utf8").digest("hex");
+}
+
+function draftRequestFingerprint(input: DraftRequestInput): string {
+  return operationRequestFingerprint("create_draft", [
+    ["accountId", true, input.accountId],
+    ["workspaceId", true, input.workspaceId],
+    ["kind", true, input.kind],
+    ["scope", true, input.scope],
+    ["roleKey", true, input.roleKey],
+    ["content", true, input.content],
+    ["provenanceSource", true, input.provenanceSource],
+    ["provenanceSourceId", true, input.provenanceSourceId],
+    ["supersedesRevisionId", true, input.supersedesRevisionId],
+    ["createdBySubjectId", true, input.createdBySubjectId],
+  ]);
+}
+
+function importLegacyRequestFingerprint(input: ImportLegacyRequestInput): string {
+  return operationRequestFingerprint("import_legacy", [
+    ["accountId", true, input.accountId],
+    ["workspaceId", true, input.workspaceId],
+    ["createdBySubjectId", true, input.createdBySubjectId],
+    ["supersedesRevisionId", true, input.supersedesRevisionId],
+  ]);
+}
+
+function activeRevisionRequestFingerprint(input: ActiveRevisionInput): string {
+  const expectedCurrentRevisionIdPresent = hasOwnField(input, "expectedCurrentRevisionId");
+  const expectedActivationVersionPresent = hasOwnField(input, "expectedActivationVersion");
+  return operationRequestFingerprint(`change_active_revision:${input.type}`, [
+    ["accountId", true, input.accountId],
+    ["workspaceId", true, input.workspaceId],
+    ["targetRevisionId", true, input.targetRevisionId],
+    [
+      "expectedCurrentRevisionId",
+      expectedCurrentRevisionIdPresent,
+      input.expectedCurrentRevisionId ?? null,
+    ],
+    [
+      "expectedActivationVersion",
+      expectedActivationVersionPresent,
+      input.expectedActivationVersion ?? null,
+    ],
+    ["actorSubjectId", true, input.actorSubjectId],
+    ["reason", true, input.reason],
+  ]);
+}
+
 function iso(value: Date | string): string {
   return (value instanceof Date ? value : new Date(value)).toISOString();
 }
 
+/**
+ * Inspect one immutable accepted attempt only when the authenticated caller is
+ * exactly its frozen initiating human. The null result deliberately conflates
+ * absence, cross-account/workspace lookup, and another subject's attempt.
+ */
+export async function getWorkspaceStateAcceptedAttemptGovernance(
+  db: Database,
+  input: { accountId: string; workspaceId: string; subjectId: string; attemptId: string },
+): Promise<WorkspaceStateAcceptedAttemptGovernance | null> {
+  return await withWorkspaceSubjectRls(db, input.workspaceId, input.subjectId, async (scopedDb) => {
+    const initiatingSubject = sql<string>`coalesce(
+        ${schema.sessionTurns.initiatingHumanSubjectId},
+        case when ${schema.sessionTurns.initiatorKind} = 'subject'
+          then ${schema.sessionTurns.initiatorSubjectId}
+        end
+      )`;
+    const [attempt] = await scopedDb
+      .select({
+        attemptId: schema.sessionTurnAttempts.id,
+        executionGeneration: schema.sessionTurnAttempts.executionGeneration,
+        acceptedAt: schema.sessionTurns.createdAt,
+      })
+      .from(schema.sessionTurnAttempts)
+      .innerJoin(
+        schema.sessionTurns,
+        and(
+          eq(schema.sessionTurns.accountId, schema.sessionTurnAttempts.accountId),
+          eq(schema.sessionTurns.workspaceId, schema.sessionTurnAttempts.workspaceId),
+          eq(schema.sessionTurns.sessionId, schema.sessionTurnAttempts.sessionId),
+          eq(schema.sessionTurns.id, schema.sessionTurnAttempts.turnId),
+        ),
+      )
+      .where(
+        and(
+          eq(schema.sessionTurnAttempts.accountId, input.accountId),
+          eq(schema.sessionTurnAttempts.workspaceId, input.workspaceId),
+          eq(schema.sessionTurnAttempts.id, input.attemptId),
+          eq(initiatingSubject, input.subjectId),
+        ),
+      )
+      .limit(1);
+    if (!attempt) return null;
+
+    const [policyRows, preferenceRows] = await Promise.all([
+      scopedDb
+        .select()
+        .from(schema.workspaceInstructionPolicySnapshots)
+        .where(
+          and(
+            eq(schema.workspaceInstructionPolicySnapshots.accountId, input.accountId),
+            eq(schema.workspaceInstructionPolicySnapshots.workspaceId, input.workspaceId),
+            eq(schema.workspaceInstructionPolicySnapshots.attemptId, input.attemptId),
+            eq(
+              schema.workspaceInstructionPolicySnapshots.executionGeneration,
+              attempt.executionGeneration,
+            ),
+          ),
+        )
+        .limit(1),
+      scopedDb
+        .select()
+        .from(schema.preferenceRegistrySnapshots)
+        .where(
+          and(
+            eq(schema.preferenceRegistrySnapshots.accountId, input.accountId),
+            eq(schema.preferenceRegistrySnapshots.workspaceId, input.workspaceId),
+            eq(schema.preferenceRegistrySnapshots.attemptId, input.attemptId),
+            eq(schema.preferenceRegistrySnapshots.executionGeneration, attempt.executionGeneration),
+            eq(schema.preferenceRegistrySnapshots.initiatingHumanSubjectId, input.subjectId),
+          ),
+        )
+        .limit(1),
+    ]);
+    const policyRow = policyRows[0] ?? null;
+    const preferenceRow = preferenceRows[0] ?? null;
+    return {
+      attemptId: attempt.attemptId,
+      executionGeneration: attempt.executionGeneration,
+      acceptedAt: iso(attempt.acceptedAt),
+      policySnapshot: policyRow
+        ? WorkspaceInstructionPolicySnapshot.parse({
+            id: policyRow.id,
+            workspaceId: policyRow.workspaceId,
+            sessionId: policyRow.sessionId,
+            turnId: policyRow.turnId,
+            attemptId: policyRow.attemptId,
+            executionGeneration: policyRow.executionGeneration,
+            policyRole: policyRow.policyRole,
+            roleSource: policyRow.roleSource,
+            entries: policyRow.entries,
+            entryHash: policyRow.entryHash,
+            createdAt: iso(policyRow.createdAt),
+          })
+        : null,
+      preferenceSnapshot: preferenceRow
+        ? (() => {
+            const snapshot = PreferenceRegistrySnapshot.parse({
+              id: preferenceRow.id,
+              workspaceId: preferenceRow.workspaceId,
+              sessionId: preferenceRow.sessionId,
+              turnId: preferenceRow.turnId,
+              attemptId: preferenceRow.attemptId,
+              executionGeneration: preferenceRow.executionGeneration,
+              initiatingHumanSubjectId: preferenceRow.initiatingHumanSubjectId,
+              descriptorHash: preferenceRow.descriptorHash,
+              descriptors: preferenceRow.descriptors,
+              truncated: preferenceRow.truncated,
+              createdAt: iso(preferenceRow.createdAt),
+            });
+            return {
+              id: snapshot.id,
+              descriptorHash: snapshot.descriptorHash,
+              descriptors: snapshot.descriptors.map((descriptor) => ({
+                id: descriptor.id,
+                revisionId: descriptor.revisionId,
+                contentHash: descriptor.contentHash,
+                activeVersion: descriptor.activeVersion,
+                scope: descriptor.scope,
+              })),
+              truncated: snapshot.truncated,
+              createdAt: snapshot.createdAt,
+            };
+          })()
+        : null,
+    };
+  });
+}
+
 type RevisionRow = typeof schema.workspaceInstructionPolicyRevisions.$inferSelect;
 type HeadRow = typeof schema.workspaceInstructionPolicyHeads.$inferSelect;
 type EventRow = typeof schema.workspaceInstructionPolicyActivationEvents.$inferSelect;
@@ -78,6 +350,7 @@ type EventRow = typeof schema.workspaceInstructionPolicyActivationEvents.$inferS
 function revisionFromRow(row: RevisionRow): WorkspaceInstructionPolicyRevision {
   return {
     id: row.id,
+    operationId: row.operationId ?? row.id,
     accountId: row.accountId,
     workspaceId: row.workspaceId,
     revision: row.revision,
@@ -113,6 +386,7 @@ function headFromRow(row: HeadRow): WorkspaceInstructionPolicyHead {
 function eventFromRow(row: EventRow): WorkspaceInstructionPolicyActivationEvent {
   return {
     id: row.id,
+    operationId: row.operationId ?? row.id,
     accountId: row.accountId,
     workspaceId: row.workspaceId,
     kind: row.kind as WorkspaceInstructionPolicyKind,
@@ -139,6 +413,20 @@ function eventFromRow(row: EventRow): WorkspaceInstructionPolicyActivationEvent
   };
 }
 
+function headFromEventRow(row: EventRow): WorkspaceInstructionPolicyHead {
+  return {
+    workspaceId: row.workspaceId,
+    kind: row.kind as WorkspaceInstructionPolicyKind,
+    scope: row.scope as WorkspaceInstructionPolicyScope,
+    roleKey: row.roleKey,
+    revisionId: row.newRevisionId,
+    revision: row.newRevision,
+    contentHash: row.newContentHash,
+    activationVersion: row.activationVersion,
+    activatedAt: iso(row.createdAt),
+  };
+}
+
 function headTargetConditions(
   workspaceId: string,
   target: WorkspaceInstructionPolicyTarget,
@@ -206,6 +494,54 @@ async function getRevisionInTransaction(
   return row ?? null;
 }
 
+async function getRevisionByOperationInTransaction(
+  db: Database,
+  workspaceId: string,
+  operationId: string,
+): Promise<RevisionRow | null> {
+  const [row] = await db
+    .select()
+    .from(schema.workspaceInstructionPolicyRevisions)
+    .where(
+      and(
+        eq(schema.workspaceInstructionPolicyRevisions.workspaceId, workspaceId),
+        or(
+          eq(schema.workspaceInstructionPolicyRevisions.operationId, operationId),
+          and(
+            isNull(schema.workspaceInstructionPolicyRevisions.operationId),
+            eq(schema.workspaceInstructionPolicyRevisions.id, operationId),
+          ),
+        ),
+      ),
+    )
+    .limit(1);
+  return row ?? null;
+}
+
+async function getEventByOperationInTransaction(
+  db: Database,
+  workspaceId: string,
+  operationId: string,
+): Promise<EventRow | null> {
+  const [row] = await db
+    .select()
+    .from(schema.workspaceInstructionPolicyActivationEvents)
+    .where(
+      and(
+        eq(schema.workspaceInstructionPolicyActivationEvents.workspaceId, workspaceId),
+        or(
+          eq(schema.workspaceInstructionPolicyActivationEvents.operationId, operationId),
+          and(
+            isNull(schema.workspaceInstructionPolicyActivationEvents.operationId),
+            eq(schema.workspaceInstructionPolicyActivationEvents.id, operationId),
+          ),
+        ),
+      ),
+    )
+    .limit(1);
+  return row ?? null;
+}
+
 async function getHeadInTransaction(
   db: Database,
   workspaceId: string,
@@ -227,10 +563,41 @@ function sameTarget(
   return left.kind === right.kind && left.scope === right.scope && left.roleKey === right.roleKey;
 }
 
+function draftReceiptMatches(row: RevisionRow, input: DraftInput): boolean {
+  return (
+    row.createdBySubjectId === input.createdBySubjectId &&
+    row.kind === input.kind &&
+    row.scope === input.scope &&
+    row.roleKey === input.roleKey &&
+    row.content === input.content &&
+    row.provenanceSource === input.provenanceSource &&
+    row.provenanceSourceId === input.provenanceSourceId &&
+    row.supersedesRevisionId === input.supersedesRevisionId
+  );
+}
+
 async function createDraftInTransaction(
   db: Database,
   input: DraftInput,
 ): Promise<WorkspaceInstructionPolicyRevision> {
+  if (await getEventByOperationInTransaction(db, input.workspaceId, input.operationId)) {
+    throw new WorkspaceInstructionPolicyOperationReuseError();
+  }
+  const existing = await getRevisionByOperationInTransaction(
+    db,
+    input.workspaceId,
+    input.operationId,
+  );
+  if (existing) {
+    if (
+      existing.requestFingerprint === null
+        ? !draftReceiptMatches(existing, input)
+        : existing.requestFingerprint !== input.requestFingerprint
+    ) {
+      throw new WorkspaceInstructionPolicyOperationReuseError();
+    }
+    return revisionFromRow(existing);
+  }
   if (input.supersedesRevisionId !== null) {
     const superseded = await getRevisionInTransaction(
       db,
@@ -246,6 +613,8 @@ async function createDraftInTransaction(
   const [created] = await db
     .insert(schema.workspaceInstructionPolicyRevisions)
     .values({
+      operationId: input.operationId,
+      requestFingerprint: input.requestFingerprint,
       accountId: input.accountId,
       workspaceId: input.workspaceId,
       kind: input.kind,
@@ -267,12 +636,14 @@ export async function createWorkspaceInstructionPolicyDraft(
   db: Database,
   input: CallerDraftInput,
 ): Promise<WorkspaceInstructionPolicyRevision> {
+  const request = { ...input, operationId: input.operationId ?? randomUUID() };
+  const normalized = { ...request, requestFingerprint: draftRequestFingerprint(request) };
   return await withRlsContext(
     db,
     { accountId: input.accountId, workspaceId: input.workspaceId },
     async (scopedDb) => {
       await lockWorkspace(scopedDb, input);
-      return await createDraftInTransaction(scopedDb, input);
+      return await createDraftInTransaction(scopedDb, normalized);
     },
   );
 }
@@ -280,18 +651,44 @@ export async function createWorkspaceInstructionPolicyDraft(
 /** Import only the stored legacy override; never materialize a deployment default or activate it. */
 export async function importLegacyWorkspaceInstructionPolicyDraft(
   db: Database,
-  input: {
-    accountId: string;
-    workspaceId: string;
-    createdBySubjectId: string;
-    supersedesRevisionId: string | null;
-  },
+  input: Omit<ImportLegacyRequestInput, "operationId"> & { operationId?: string },
 ): Promise<WorkspaceInstructionPolicyRevision> {
+  const request = { ...input, operationId: input.operationId ?? randomUUID() };
+  const normalized = {
+    ...request,
+    requestFingerprint: importLegacyRequestFingerprint(request),
+  };
   return await withRlsContext(
     db,
     { accountId: input.accountId, workspaceId: input.workspaceId },
     async (scopedDb) => {
       const workspace = await lockWorkspace(scopedDb, input);
+      if (
+        await getEventByOperationInTransaction(scopedDb, input.workspaceId, normalized.operationId)
+      ) {
+        throw new WorkspaceInstructionPolicyOperationReuseError();
+      }
+      const existing = await getRevisionByOperationInTransaction(
+        scopedDb,
+        input.workspaceId,
+        normalized.operationId,
+      );
+      if (existing) {
+        if (
+          existing.requestFingerprint === null
+            ? existing.createdBySubjectId !== input.createdBySubjectId ||
+              existing.kind !== "charter" ||
+              existing.scope !== "global" ||
+              existing.roleKey !== null ||
+              existing.provenanceSource !== "legacy_import" ||
+              existing.provenanceSourceId !== "workspaces.agent_instructions" ||
+              existing.supersedesRevisionId !== input.supersedesRevisionId
+            : existing.requestFingerprint !== normalized.requestFingerprint
+        ) {
+          throw new WorkspaceInstructionPolicyOperationReuseError();
+        }
+        return revisionFromRow(existing);
+      }
       if (workspace.agentInstructions === null) {
         throw new WorkspaceInstructionPolicyLegacyUnavailableError();
       }
@@ -304,7 +701,7 @@ export async function importLegacyWorkspaceInstructionPolicyDraft(
         );
       }
       return await createDraftInTransaction(scopedDb, {
-        ...input,
+        ...normalized,
         kind: "charter",
         scope: "global",
         roleKey: null,
@@ -474,16 +871,9 @@ export async function diffWorkspaceInstructionPolicyRevisions(
 
 async function changeActiveRevision(
   db: Database,
-  input: {
-    accountId: string;
-    workspaceId: string;
-    targetRevisionId: string;
-    expectedCurrentRevisionId: string | null;
-    actorSubjectId: string;
-    reason: string;
-    type: WorkspaceInstructionPolicyActivationType;
-  },
+  input: ActiveRevisionInput,
 ): Promise<WorkspaceInstructionPolicyActivationResponse> {
+  const requestFingerprint = activeRevisionRequestFingerprint(input);
   return await withRlsContext(
     db,
     { accountId: input.accountId, workspaceId: input.workspaceId },
@@ -491,6 +881,34 @@ async function changeActiveRevision(
       // This row lock serializes both an absent-head first activation and later
       // updates, so every loser can return the authoritative typed conflict.
       await lockWorkspace(scopedDb, input);
+      if (
+        await getRevisionByOperationInTransaction(scopedDb, input.workspaceId, input.operationId)
+      ) {
+        throw new WorkspaceInstructionPolicyOperationReuseError();
+      }
+      const existingEvent = await getEventByOperationInTransaction(
+        scopedDb,
+        input.workspaceId,
+        input.operationId,
+      );
+      if (existingEvent) {
+        const legacyRequestMatches =
+          hasOwnField(input, "expectedCurrentRevisionId") &&
+          !hasOwnField(input, "expectedActivationVersion") &&
+          existingEvent.type === input.type &&
+          existingEvent.newRevisionId === input.targetRevisionId &&
+          existingEvent.oldRevisionId === input.expectedCurrentRevisionId &&
+          existingEvent.actorSubjectId === input.actorSubjectId &&
+          existingEvent.reason === input.reason;
+        if (
+          existingEvent.requestFingerprint === null
+            ? !legacyRequestMatches
+            : existingEvent.requestFingerprint !== requestFingerprint
+        ) {
+          throw new WorkspaceInstructionPolicyOperationReuseError();
+        }
+        return { head: headFromEventRow(existingEvent), event: eventFromRow(existingEvent) };
+      }
       const targetRow = await getRevisionInTransaction(
         scopedDb,
         input.workspaceId,
@@ -505,7 +923,11 @@ async function changeActiveRevision(
       };
       const currentRow = await getHeadInTransaction(scopedDb, input.workspaceId, targetIdentity);
       const currentHead = currentRow ? headFromRow(currentRow) : null;
-      if ((currentHead?.revisionId ?? null) !== input.expectedCurrentRevisionId) {
+      if (
+        (currentHead?.revisionId ?? null) !== input.expectedCurrentRevisionId ||
+        (input.expectedActivationVersion !== undefined &&
+          (currentHead?.activationVersion ?? 0) !== input.expectedActivationVersion)
+      ) {
         throw new WorkspaceInstructionPolicyConflictError(currentHead);
       }
       if (currentHead?.revisionId === target.id) {
@@ -540,6 +962,8 @@ async function changeActiveRevision(
       const [eventRow] = await scopedDb
         .insert(schema.workspaceInstructionPolicyActivationEvents)
         .values({
+          operationId: input.operationId,
+          requestFingerprint,
           accountId: input.accountId,
           workspaceId: input.workspaceId,
           ...targetIdentity,
@@ -594,16 +1018,19 @@ async function changeActiveRevision(
 export async function activateWorkspaceInstructionPolicyRevision(
   db: Database,
   input: {
+    operationId?: string;
     accountId: string;
     workspaceId: string;
     revisionId: string;
     expectedCurrentRevisionId: string | null;
+    expectedActivationVersion?: number;
     actorSubjectId: string;
     reason: string;
   },
 ): Promise<WorkspaceInstructionPolicyActivationResponse> {
   return await changeActiveRevision(db, {
     ...input,
+    operationId: input.operationId ?? randomUUID(),
     targetRevisionId: input.revisionId,
     type: "activate",
   });
@@ -612,13 +1039,129 @@ export async function activateWorkspaceInstructionPolicyRevision(
 export async function rollbackWorkspaceInstructionPolicyRevision(
   db: Database,
   input: {
+    operationId?: string;
     accountId: string;
     workspaceId: string;
     targetRevisionId: string;
     expectedCurrentRevisionId: string;
+    expectedActivationVersion?: number;
     actorSubjectId: string;
     reason: string;
   },
 ): Promise<WorkspaceInstructionPolicyActivationResponse> {
-  return await changeActiveRevision(db, { ...input, type: "rollback" });
+  return await changeActiveRevision(db, {
+    ...input,
+    operationId: input.operationId ?? randomUUID(),
+    type: "rollback",
+  });
+}
+
+/**
+ * Freeze (or replay) the exact active charter/global/role policy set for one
+ * accepted attempt, then resolve only those immutable revisions. The snapshot
+ * stores bounded descriptors/hashes; full policy text remains in the revision
+ * table and cannot be widened by a later head activation.
+ */
+export async function getOrCreateWorkspaceInstructionPolicySnapshot(
+  db: Database,
+  claims: WorkspaceInstructionPolicyAttemptClaims,
+) {
+  try {
+    return await withWorkspaceRls(db, claims.workspaceId, async (scopedDb) => {
+      const rows = (await scopedDb.execute(sql`
+        SELECT
+          snapshot.id,
+          snapshot.workspace_id AS "workspaceId",
+          snapshot.session_id AS "sessionId",
+          snapshot.turn_id AS "turnId",
+          snapshot.attempt_id AS "attemptId",
+          snapshot.execution_generation AS "executionGeneration",
+          snapshot.policy_role AS "policyRole",
+          snapshot.role_source AS "roleSource",
+          snapshot.entries,
+          snapshot.entry_hash AS "entryHash",
+          snapshot.created_at AS "createdAt"
+        FROM workspace_instruction_policy_get_or_create_snapshot(
+          ${claims.accountId}::uuid,
+          ${claims.workspaceId}::uuid,
+          ${claims.sessionId}::uuid,
+          ${claims.turnId}::uuid,
+          ${claims.attemptId}::uuid,
+          ${claims.executionGeneration}
+        ) snapshot
+      `)) as unknown as Array<{
+        id: string;
+        workspaceId: string;
+        sessionId: string;
+        turnId: string;
+        attemptId: string;
+        executionGeneration: number;
+        policyRole: string | null;
+        roleSource: string;
+        entries: unknown;
+        entryHash: string;
+        createdAt: Date | string;
+      }>;
+      const row = rows[0];
+      if (!row) {
+        throw new WorkspaceInstructionPolicySnapshotAuthorityError(
+          "Instruction-policy snapshot authority conflicts with the accepted attempt",
+        );
+      }
+      const snapshot = WorkspaceInstructionPolicySnapshot.parse({
+        ...row,
+        createdAt: iso(row.createdAt),
+      });
+      if (snapshot.entries.length === 0) {
+        return ResolvedWorkspaceInstructionPolicySnapshot.parse(snapshot);
+      }
+
+      const revisionIds = snapshot.entries.map((entry) => entry.revisionId);
+      const revisions = await scopedDb
+        .select()
+        .from(schema.workspaceInstructionPolicyRevisions)
+        .where(
+          and(
+            eq(schema.workspaceInstructionPolicyRevisions.accountId, claims.accountId),
+            eq(schema.workspaceInstructionPolicyRevisions.workspaceId, claims.workspaceId),
+            inArray(schema.workspaceInstructionPolicyRevisions.id, revisionIds),
+          ),
+        );
+      const revisionsById = new Map(revisions.map((revision) => [revision.id, revision]));
+      const resolvedEntries = snapshot.entries.map((entry) => {
+        const revision = revisionsById.get(entry.revisionId);
+        if (!revision || !snapshotEntryMatchesRevision(entry, revision)) {
+          throw new WorkspaceInstructionPolicyInvalidOperationError(
+            "Instruction-policy snapshot references an inexact immutable revision",
+          );
+        }
+        return { ...entry, content: revision.content };
+      });
+      return ResolvedWorkspaceInstructionPolicySnapshot.parse({
+        ...snapshot,
+        entries: resolvedEntries,
+      });
+    });
+  } catch (error) {
+    if (["40001", "42501"].includes(nestedPostgresSqlState(error) ?? "")) {
+      throw new WorkspaceInstructionPolicySnapshotAuthorityError(
+        "Instruction-policy snapshot requires the exact current attempt and generation",
+      );
+    }
+    throw error;
+  }
+}
+
+function snapshotEntryMatchesRevision(
+  entry: WorkspaceInstructionPolicySnapshotEntry,
+  revision: RevisionRow,
+): boolean {
+  return (
+    revision.id === entry.revisionId &&
+    revision.revision === entry.revision &&
+    revision.contentHash === entry.contentHash &&
+    revision.kind === entry.kind &&
+    revision.scope === entry.scope &&
+    revision.roleKey === entry.roleKey
+  );
 }