@opengeni/db 0.23.0 → 0.27.0

package/src/workspace-instruction-policies.ts

@@ -1,5 +1,6 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import {
+  PreferenceRegistrySnapshot,
   ResolvedWorkspaceInstructionPolicySnapshot,
   WORKSPACE_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
   WorkspaceInstructionPolicySnapshot,
@@ -14,19 +15,23 @@ import type {
   WorkspaceInstructionPolicyKind,
   WorkspaceInstructionPolicyListQuery,
   WorkspaceInstructionPolicyListResponse,
+  WorkspaceInstructionPolicyOnboardingProposal,
+  WorkspaceInstructionPolicyOnboardingProposalListQuery,
+  WorkspaceInstructionPolicyOnboardingProposalListResponse,
   WorkspaceInstructionPolicyProvenanceSource,
   WorkspaceInstructionPolicyRevision,
   WorkspaceInstructionPolicyScope,
   WorkspaceInstructionPolicySnapshotEntry,
   WorkspaceInstructionPolicyTarget,
 } from "@opengeni/contracts";
-import { and, asc, desc, eq, inArray, isNull, lt, sql, 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;
@@ -36,10 +41,52 @@ 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;
+};
+
+type OnboardingProposalRequestInput = WorkspaceInstructionPolicyTarget & {
+  operationId: string;
+  accountId: string;
+  workspaceId: string;
+  content: string;
+  sourceId: string;
+  sourceVersion: string;
+  confidenceBps: number;
+  expectedCurrentRevisionId: string | null;
+  expectedActivationVersion: number;
+  createdBySubjectId: string;
+};
+
+type OnboardingProposalInput = OnboardingProposalRequestInput & {
+  requestFingerprint: string;
+};
+
 export class WorkspaceInstructionPolicyConflictError extends Error {
   readonly name = "WorkspaceInstructionPolicyConflictError";
   readonly code = "WORKSPACE_INSTRUCTION_POLICY_CONFLICT";
@@ -49,6 +96,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";
 
@@ -69,6 +125,43 @@ export class WorkspaceInstructionPolicyLegacyUnavailableError extends Error {
   }
 }
 
+export class WorkspaceInstructionPolicyOnboardingProposalContentError extends Error {
+  readonly name = "WorkspaceInstructionPolicyOnboardingProposalContentError";
+
+  constructor(
+    readonly code:
+      | "WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_PROPOSAL_EMPTY"
+      | "WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_PROPOSAL_OVERSIZED",
+  ) {
+    super(
+      code === "WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_PROPOSAL_EMPTY"
+        ? "An onboarding proposal must contain non-blank instruction-policy content"
+        : `An onboarding proposal must not exceed ${WORKSPACE_INSTRUCTION_POLICY_CONTENT_MAX_CHARS} characters`,
+    );
+  }
+}
+
+export class WorkspaceInstructionPolicyOnboardingProposalStaleError extends Error {
+  readonly name = "WorkspaceInstructionPolicyOnboardingProposalStaleError";
+  readonly code = "WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_PROPOSAL_STALE";
+
+  constructor(readonly currentHead: WorkspaceInstructionPolicyHead | null) {
+    super("The onboarding proposal was prepared against a stale active policy baseline");
+  }
+}
+
+export class WorkspaceInstructionPolicyOnboardingProposalConflictError extends Error {
+  readonly name = "WorkspaceInstructionPolicyOnboardingProposalConflictError";
+  readonly code = "WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_PROPOSAL_CONFLICT";
+
+  constructor(
+    readonly existingProposalId: string,
+    readonly existingDraftRevisionId: string,
+  ) {
+    super("This onboarding source version already proposed a draft for the policy target");
+  }
+}
+
 export class WorkspaceInstructionPolicySnapshotAuthorityError extends Error {
   readonly name = "WorkspaceInstructionPolicySnapshotAuthorityError";
 }
@@ -82,21 +175,258 @@ export type WorkspaceInstructionPolicyAttemptClaims = {
   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 onboardingProposalRequestFingerprint(input: OnboardingProposalRequestInput): string {
+  return operationRequestFingerprint("create_onboarding_proposal", [
+    ["accountId", true, input.accountId],
+    ["workspaceId", true, input.workspaceId],
+    ["kind", true, input.kind],
+    ["scope", true, input.scope],
+    ["roleKey", true, input.roleKey],
+    ["content", true, input.content],
+    ["sourceId", true, input.sourceId],
+    ["sourceVersion", true, input.sourceVersion],
+    ["confidenceBps", true, input.confidenceBps],
+    ["expectedCurrentRevisionId", true, input.expectedCurrentRevisionId],
+    ["expectedActivationVersion", true, input.expectedActivationVersion],
+    ["createdBySubjectId", true, input.createdBySubjectId],
+  ]);
+}
+
 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;
+type OnboardingProposalRow =
+  typeof schema.workspaceInstructionPolicyOnboardingProposals.$inferSelect;
 
 function revisionFromRow(row: RevisionRow): WorkspaceInstructionPolicyRevision {
   return {
     id: row.id,
+    operationId: row.operationId ?? row.id,
     accountId: row.accountId,
     workspaceId: row.workspaceId,
     revision: row.revision,
@@ -132,6 +462,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,
@@ -158,6 +489,58 @@ function eventFromRow(row: EventRow): WorkspaceInstructionPolicyActivationEvent
   };
 }
 
+function onboardingProposalFromRow(
+  row: OnboardingProposalRow,
+  draftRow: RevisionRow,
+): WorkspaceInstructionPolicyOnboardingProposal {
+  return {
+    id: row.id,
+    operationId: row.operationId,
+    accountId: row.accountId,
+    workspaceId: row.workspaceId,
+    kind: row.kind as WorkspaceInstructionPolicyKind,
+    scope: row.scope as WorkspaceInstructionPolicyScope,
+    roleKey: row.roleKey,
+    source: {
+      id: row.sourceId,
+      version: row.sourceVersion,
+      confidenceBps: row.confidenceBps,
+    },
+    baseline:
+      row.baselineRevisionId === null
+        ? null
+        : {
+            workspaceId: row.workspaceId,
+            kind: row.kind as WorkspaceInstructionPolicyKind,
+            scope: row.scope as WorkspaceInstructionPolicyScope,
+            roleKey: row.roleKey,
+            revisionId: row.baselineRevisionId,
+            revision: row.baselineRevision!,
+            contentHash: row.baselineContentHash!,
+            activationVersion: row.baselineActivationVersion,
+            activatedAt: iso(row.baselineActivatedAt!),
+          },
+    draft: revisionFromRow(draftRow),
+    status: "proposed",
+    createdBySubjectId: row.createdBySubjectId,
+    createdAt: iso(row.createdAt),
+  };
+}
+
+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,
@@ -225,6 +608,109 @@ 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 getOnboardingProposalByOperationInTransaction(
+  db: Database,
+  workspaceId: string,
+  operationId: string,
+): Promise<OnboardingProposalRow | null> {
+  const [row] = await db
+    .select()
+    .from(schema.workspaceInstructionPolicyOnboardingProposals)
+    .where(
+      and(
+        eq(schema.workspaceInstructionPolicyOnboardingProposals.workspaceId, workspaceId),
+        eq(schema.workspaceInstructionPolicyOnboardingProposals.operationId, operationId),
+      ),
+    )
+    .limit(1);
+  return row ?? null;
+}
+
+async function getOnboardingProposalBySourceVersionInTransaction(
+  db: Database,
+  input: Pick<
+    OnboardingProposalRequestInput,
+    "workspaceId" | "kind" | "scope" | "roleKey" | "sourceId" | "sourceVersion"
+  >,
+): Promise<OnboardingProposalRow | null> {
+  const [row] = await db
+    .select()
+    .from(schema.workspaceInstructionPolicyOnboardingProposals)
+    .where(
+      and(
+        eq(schema.workspaceInstructionPolicyOnboardingProposals.workspaceId, input.workspaceId),
+        eq(schema.workspaceInstructionPolicyOnboardingProposals.kind, input.kind),
+        eq(schema.workspaceInstructionPolicyOnboardingProposals.scope, input.scope),
+        input.roleKey === null
+          ? isNull(schema.workspaceInstructionPolicyOnboardingProposals.roleKey)
+          : eq(schema.workspaceInstructionPolicyOnboardingProposals.roleKey, input.roleKey),
+        eq(schema.workspaceInstructionPolicyOnboardingProposals.sourceId, input.sourceId),
+        eq(schema.workspaceInstructionPolicyOnboardingProposals.sourceVersion, input.sourceVersion),
+      ),
+    )
+    .limit(1);
+  return row ?? null;
+}
+
+async function resolveOnboardingProposalInTransaction(
+  db: Database,
+  row: OnboardingProposalRow,
+): Promise<WorkspaceInstructionPolicyOnboardingProposal> {
+  const draftRow = await getRevisionInTransaction(db, row.workspaceId, row.draftRevisionId);
+  if (!draftRow) {
+    throw new Error("Workspace instruction-policy onboarding proposal lost its draft revision");
+  }
+  return onboardingProposalFromRow(row, draftRow);
+}
+
 async function getHeadInTransaction(
   db: Database,
   workspaceId: string,
@@ -246,10 +732,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,
@@ -265,6 +782,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,
@@ -277,8 +796,19 @@ async function createDraftInTransaction(
       supersedesRevisionId: input.supersedesRevisionId,
       createdBySubjectId: input.createdBySubjectId,
     })
+    .onConflictDoNothing()
     .returning();
-  if (!created) throw new Error("Workspace instruction-policy draft was not created");
+  if (!created) {
+    const concurrent = await getRevisionByOperationInTransaction(
+      db,
+      input.workspaceId,
+      input.operationId,
+    );
+    if (!concurrent || concurrent.requestFingerprint !== input.requestFingerprint) {
+      throw new WorkspaceInstructionPolicyOperationReuseError();
+    }
+    return revisionFromRow(concurrent);
+  }
   return revisionFromRow(created);
 }
 
@@ -286,12 +816,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);
     },
   );
 }
@@ -299,18 +831,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();
       }
@@ -323,7 +881,7 @@ export async function importLegacyWorkspaceInstructionPolicyDraft(
         );
       }
       return await createDraftInTransaction(scopedDb, {
-        ...input,
+        ...normalized,
         kind: "charter",
         scope: "global",
         roleKey: null,
@@ -335,6 +893,206 @@ export async function importLegacyWorkspaceInstructionPolicyDraft(
   );
 }
 
+export async function createWorkspaceInstructionPolicyOnboardingProposal(
+  db: Database,
+  input: Omit<OnboardingProposalRequestInput, "operationId"> & { operationId?: string },
+): Promise<WorkspaceInstructionPolicyOnboardingProposal> {
+  if (input.content.trim().length === 0) {
+    throw new WorkspaceInstructionPolicyOnboardingProposalContentError(
+      "WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_PROPOSAL_EMPTY",
+    );
+  }
+  if (input.content.length > WORKSPACE_INSTRUCTION_POLICY_CONTENT_MAX_CHARS) {
+    throw new WorkspaceInstructionPolicyOnboardingProposalContentError(
+      "WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_PROPOSAL_OVERSIZED",
+    );
+  }
+  const request: OnboardingProposalRequestInput = {
+    ...input,
+    operationId: input.operationId ?? randomUUID(),
+    sourceId: input.sourceId.trim(),
+    sourceVersion: input.sourceVersion.trim(),
+  };
+  const normalized: OnboardingProposalInput = {
+    ...request,
+    requestFingerprint: onboardingProposalRequestFingerprint(request),
+  };
+  return await withRlsContext(
+    db,
+    { accountId: input.accountId, workspaceId: input.workspaceId },
+    async (scopedDb) => {
+      await lockWorkspace(scopedDb, input);
+      const existing = await getOnboardingProposalByOperationInTransaction(
+        scopedDb,
+        input.workspaceId,
+        normalized.operationId,
+      );
+      if (existing) {
+        if (existing.requestFingerprint !== normalized.requestFingerprint) {
+          throw new WorkspaceInstructionPolicyOperationReuseError();
+        }
+        return await resolveOnboardingProposalInTransaction(scopedDb, existing);
+      }
+      if (
+        (await getEventByOperationInTransaction(
+          scopedDb,
+          input.workspaceId,
+          normalized.operationId,
+        )) ||
+        (await getRevisionByOperationInTransaction(
+          scopedDb,
+          input.workspaceId,
+          normalized.operationId,
+        ))
+      ) {
+        throw new WorkspaceInstructionPolicyOperationReuseError();
+      }
+
+      const target: WorkspaceInstructionPolicyTarget = {
+        kind: normalized.kind,
+        scope: normalized.scope,
+        roleKey: normalized.roleKey,
+      };
+      const currentRow = await getHeadInTransaction(scopedDb, input.workspaceId, target);
+      const currentHead = currentRow ? headFromRow(currentRow) : null;
+      if (
+        (currentHead?.revisionId ?? null) !== normalized.expectedCurrentRevisionId ||
+        (currentHead?.activationVersion ?? 0) !== normalized.expectedActivationVersion
+      ) {
+        throw new WorkspaceInstructionPolicyOnboardingProposalStaleError(currentHead);
+      }
+
+      const sourceConflict = await getOnboardingProposalBySourceVersionInTransaction(
+        scopedDb,
+        normalized,
+      );
+      if (sourceConflict) {
+        throw new WorkspaceInstructionPolicyOnboardingProposalConflictError(
+          sourceConflict.id,
+          sourceConflict.draftRevisionId,
+        );
+      }
+
+      const proposalId = randomUUID();
+      const draft = await createDraftInTransaction(scopedDb, {
+        operationId: normalized.operationId,
+        requestFingerprint: normalized.requestFingerprint,
+        accountId: normalized.accountId,
+        workspaceId: normalized.workspaceId,
+        kind: normalized.kind,
+        scope: normalized.scope,
+        roleKey: normalized.roleKey,
+        content: normalized.content,
+        provenanceSource: "onboarding",
+        provenanceSourceId: proposalId,
+        supersedesRevisionId: currentHead?.revisionId ?? null,
+        createdBySubjectId: normalized.createdBySubjectId,
+      });
+      const createdAt = new Date();
+      const [created] = await scopedDb
+        .insert(schema.workspaceInstructionPolicyOnboardingProposals)
+        .values({
+          id: proposalId,
+          operationId: normalized.operationId,
+          requestFingerprint: normalized.requestFingerprint,
+          accountId: normalized.accountId,
+          workspaceId: normalized.workspaceId,
+          kind: normalized.kind,
+          scope: normalized.scope,
+          roleKey: normalized.roleKey,
+          sourceId: normalized.sourceId,
+          sourceVersion: normalized.sourceVersion,
+          confidenceBps: normalized.confidenceBps,
+          baselineRevisionId: currentHead?.revisionId ?? null,
+          baselineRevision: currentHead?.revision ?? null,
+          baselineContentHash: currentHead?.contentHash ?? null,
+          baselineActivationVersion: currentHead?.activationVersion ?? 0,
+          baselineActivatedAt: currentHead ? new Date(currentHead.activatedAt) : null,
+          draftRevisionId: draft.id,
+          draftRevision: draft.revision,
+          draftContentHash: draft.contentHash,
+          status: "proposed",
+          createdBySubjectId: normalized.createdBySubjectId,
+          createdAt,
+        })
+        .onConflictDoNothing()
+        .returning();
+      if (created) {
+        const draftRow = await getRevisionInTransaction(scopedDb, input.workspaceId, draft.id);
+        if (!draftRow) throw new Error("Onboarding proposal draft was not recorded");
+        return onboardingProposalFromRow(created, draftRow);
+      }
+
+      const concurrentOperation = await getOnboardingProposalByOperationInTransaction(
+        scopedDb,
+        input.workspaceId,
+        normalized.operationId,
+      );
+      if (concurrentOperation) {
+        if (concurrentOperation.requestFingerprint !== normalized.requestFingerprint) {
+          throw new WorkspaceInstructionPolicyOperationReuseError();
+        }
+        return await resolveOnboardingProposalInTransaction(scopedDb, concurrentOperation);
+      }
+      const concurrentSource = await getOnboardingProposalBySourceVersionInTransaction(
+        scopedDb,
+        normalized,
+      );
+      if (concurrentSource) {
+        throw new WorkspaceInstructionPolicyOnboardingProposalConflictError(
+          concurrentSource.id,
+          concurrentSource.draftRevisionId,
+        );
+      }
+      throw new Error("Workspace instruction-policy onboarding proposal was not created");
+    },
+  );
+}
+
+export async function listWorkspaceInstructionPolicyOnboardingProposals(
+  db: Database,
+  workspaceId: string,
+  query: WorkspaceInstructionPolicyOnboardingProposalListQuery,
+): Promise<WorkspaceInstructionPolicyOnboardingProposalListResponse> {
+  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    const rows = await scopedDb
+      .select()
+      .from(schema.workspaceInstructionPolicyOnboardingProposals)
+      .where(eq(schema.workspaceInstructionPolicyOnboardingProposals.workspaceId, workspaceId))
+      .orderBy(
+        desc(schema.workspaceInstructionPolicyOnboardingProposals.createdAt),
+        desc(schema.workspaceInstructionPolicyOnboardingProposals.id),
+      )
+      .limit(query.limit + 1);
+    const truncated = rows.length > query.limit;
+    const page = rows.slice(0, query.limit);
+    if (page.length === 0) return { proposals: [], truncated };
+    const revisions = await scopedDb
+      .select()
+      .from(schema.workspaceInstructionPolicyRevisions)
+      .where(
+        and(
+          eq(schema.workspaceInstructionPolicyRevisions.workspaceId, workspaceId),
+          inArray(
+            schema.workspaceInstructionPolicyRevisions.id,
+            page.map((proposal) => proposal.draftRevisionId),
+          ),
+        ),
+      );
+    const revisionsById = new Map(revisions.map((revision) => [revision.id, revision]));
+    return {
+      proposals: page.map((proposal) => {
+        const draft = revisionsById.get(proposal.draftRevisionId);
+        if (!draft) {
+          throw new Error("Workspace instruction-policy onboarding proposal lost its draft");
+        }
+        return onboardingProposalFromRow(proposal, draft);
+      }),
+      truncated,
+    };
+  });
+}
+
 function listFilterConditions(
   workspaceId: string,
   query: WorkspaceInstructionPolicyListQuery,
@@ -493,16 +1251,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 },
@@ -510,6 +1261,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,
@@ -524,7 +1303,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) {
@@ -559,6 +1342,8 @@ async function changeActiveRevision(
       const [eventRow] = await scopedDb
         .insert(schema.workspaceInstructionPolicyActivationEvents)
         .values({
+          operationId: input.operationId,
+          requestFingerprint,
           accountId: input.accountId,
           workspaceId: input.workspaceId,
           ...targetIdentity,
@@ -613,16 +1398,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",
   });
@@ -631,15 +1419,21 @@ 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",
+  });
 }
 
 /**