@opengeni/api-router 0.17.0 → 0.21.0

package/src/routes/connections.ts

@@ -13,6 +13,8 @@ import {
 import {
   GOOGLE_DRIVE_PROVIDER_DOMAIN,
   GoogleDriveConnectionMetadata,
+  GoogleDriveDisconnectRequest,
+  GoogleDriveLifecycleActionRequest,
   GoogleDriveOAuthStartRequest,
   GoogleDriveOAuthStartResponse,
 } from "@opengeni/contracts/google-drive";
@@ -47,8 +49,10 @@ import { HTTPException } from "hono/http-exception";
 import {
   browseGoogleDrive,
   completeGoogleDriveOAuthCallback,
+  disconnectGoogleDrive,
   saveGoogleDriveSource,
   startGoogleDriveOAuth,
+  transitionGoogleDriveLifecycle,
 } from "../integrations/google-drive";
 import {
   completeMcpOAuthCallback,
@@ -288,6 +292,29 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     return c.redirect(result.redirectTo, 302);
   });
 
+  app.patch(
+    "/v1/workspaces/:workspaceId/connections/google-drive/:connectionId/lifecycle",
+    async (c) => {
+      assertIntegrationsEnabled();
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+      const parsed = GoogleDriveLifecycleActionRequest.safeParse(await c.req.json());
+      if (!parsed.success) {
+        throw new HTTPException(400, { message: "invalid Google Drive lifecycle request" });
+      }
+      return c.json(
+        ConnectionResponse.parse({
+          connection: await transitionGoogleDriveLifecycle(deps, {
+            workspaceId,
+            subjectId: grant.subjectId,
+            connectionId: c.req.param("connectionId"),
+            payload: parsed.data,
+          }),
+        }),
+      );
+    },
+  );
+
   app.get(
     "/v1/workspaces/:workspaceId/connections/google-drive/:connectionId/browse",
     async (c) => {
@@ -421,18 +448,43 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!existing) {
       throw new HTTPException(404, { message: "connection not found" });
     }
-    const connection = isOpenGeniSlackBotConnection(existing)
-      ? await revokeConnectionWithSlackBotSuccessAudit(db, {
-          accountId: grant.accountId,
+    const isGoogleDrive =
+      existing.subjectId === grant.subjectId &&
+      existing.providerDomain === GOOGLE_DRIVE_PROVIDER_DOMAIN &&
+      existing.kind === "oauth2" &&
+      GoogleDriveConnectionMetadata.safeParse(existing.metadata).success;
+    const googleDriveDisconnect = isGoogleDrive
+      ? GoogleDriveDisconnectRequest.safeParse(await c.req.json().catch(() => null))
+      : null;
+    if (googleDriveDisconnect && !googleDriveDisconnect.success) {
+      throw new HTTPException(400, {
+        message:
+          googleDriveDisconnect.error.issues[0]?.message ??
+          "invalid Google Drive disconnect request",
+      });
+    }
+    if (existing.status === "revoked" && !isGoogleDrive) {
+      return c.json(ConnectionResponse.parse({ connection: existing }));
+    }
+    const connection = isGoogleDrive
+      ? await disconnectGoogleDrive(deps, {
           workspaceId,
           subjectId: grant.subjectId,
-          connectionId,
-          expectedVersion: existing.version,
-          credentialRole: OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
-          credentialLabel: OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
-          slackTeamId: openGeniSlackBotMetadata(existing.metadata)!.slackTeamId,
+          connection: existing,
+          payload: googleDriveDisconnect!.data,
         })
-      : await revokeConnection(db, workspaceId, connectionId, grant.subjectId);
+      : isOpenGeniSlackBotConnection(existing)
+        ? await revokeConnectionWithSlackBotSuccessAudit(db, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+            connectionId,
+            expectedVersion: existing.version,
+            credentialRole: OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
+            credentialLabel: OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
+            slackTeamId: openGeniSlackBotMetadata(existing.metadata)!.slackTeamId,
+          })
+        : await revokeConnection(db, workspaceId, connectionId, grant.subjectId, existing.version);
     if (!connection) {
       throw new HTTPException(409, { message: "connection changed during disconnect; try again" });
     }

package/src/routes/documents.ts

@@ -6,6 +6,7 @@ import {
   Document,
   DocumentBase,
   DocumentSearchRequest,
+  DocumentSearchResponse,
   KnowledgeMemory,
   KnowledgeMemorySearchRequest,
   MoveDocumentRequest,
@@ -34,12 +35,12 @@ import {
   listDocuments,
   moveDocumentToBase,
   queueDocumentForReindex,
-  searchDocuments,
+  searchEffectiveDocuments,
 } from "@opengeni/documents";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
-import { requireAccessGrant } from "@opengeni/core";
+import { requireAccessGrant, requireAccessGrantAuthorization } from "@opengeni/core";
 import { recordWorkspaceUsage, requireLimit } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { buildDocumentsMcpServer } from "../mcp/documents";
@@ -85,7 +86,8 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.post("/v1/workspaces/:workspaceId/document-bases/:baseId/documents", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:manage");
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "documents:manage");
+    const { grant } = access;
     if (!objectStorage) {
       throw new HTTPException(503, { message: "object storage is not configured" });
     }
@@ -96,6 +98,11 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
       quantity: 0,
     });
     const payload = AddDocumentRequest.parse(await c.req.json());
+    const organizationAuthorityGranted =
+      access.accountGrant?.permissions.includes("account:admin") === true;
+    if (payload.authorityKind === "organization" && !organizationAuthorityGranted) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
     try {
       const document = await addDocumentToBase(db, {
         ...payload,
@@ -103,6 +110,8 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
         workspaceId,
         baseId: c.req.param("baseId"),
         createdBy: grant.subjectId,
+        initiatingSubjectId: grant.subjectId,
+        organizationAuthorityGranted,
         access: { viewerSubjectId: grant.subjectId },
       });
       const wasCreated =
@@ -114,6 +123,9 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
               accountId: grant.accountId,
               workspaceId,
               documentId: document.id,
+              authorityKind: document.authorityKind,
+              authorityWorkspaceId: document.authorityWorkspaceId,
+              authoritySubjectId: document.authoritySubjectId,
             })) ?? document);
       if (indexed.status === "ready") {
         await recordWorkspaceUsage(deps, {
@@ -150,13 +162,28 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
     "/v1/workspaces/:workspaceId/document-bases/:baseId/documents/:documentId",
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant(c, deps, workspaceId, "documents:manage");
+      const authorization = await requireAccessGrantAuthorization(
+        c,
+        deps,
+        workspaceId,
+        "documents:manage",
+      );
+      const { grant } = authorization;
+      const organizationAuthorityGranted = hasAccountAdminAuthority(authorization);
       try {
+        const document = await getDocument(db, workspaceId, c.req.param("documentId"), {
+          viewerSubjectId: grant.subjectId,
+        });
+        if (!document || document.baseId !== c.req.param("baseId")) {
+          throw new HTTPException(404, { message: "document not found" });
+        }
+        requireOrganizationDocumentAuthority(document.authorityKind, organizationAuthorityGranted);
         await deleteDocumentFromBase(db, {
           accountId: grant.accountId,
           workspaceId,
           baseId: c.req.param("baseId"),
           documentId: c.req.param("documentId"),
+          organizationAuthorityGranted,
           access: { viewerSubjectId: grant.subjectId },
         });
         return c.body(null, 204);
@@ -173,7 +200,14 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
     "/v1/workspaces/:workspaceId/document-bases/:baseId/documents/:documentId/reindex",
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant(c, deps, workspaceId, "documents:manage");
+      const authorization = await requireAccessGrantAuthorization(
+        c,
+        deps,
+        workspaceId,
+        "documents:manage",
+      );
+      const { grant } = authorization;
+      const organizationAuthorityGranted = hasAccountAdminAuthority(authorization);
       if (!objectStorage) {
         throw new HTTPException(503, { message: "object storage is not configured" });
       }
@@ -190,20 +224,30 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
         if (!document) {
           throw new HTTPException(404, { message: "document not found" });
         }
+        requireOrganizationDocumentAuthority(document.authorityKind, organizationAuthorityGranted);
         if (document.status !== "failed") {
           throw new HTTPException(422, { message: "only failed documents can be retried" });
         }
         if (document.baseId !== c.req.param("baseId")) {
           throw new HTTPException(404, { message: "document not found" });
         }
-        const queued = await queueDocumentForReindex(db, workspaceId, document.id, {
-          viewerSubjectId: grant.subjectId,
-        });
+        const queued = await queueDocumentForReindex(
+          db,
+          workspaceId,
+          document.id,
+          {
+            viewerSubjectId: grant.subjectId,
+          },
+          organizationAuthorityGranted,
+        );
         const indexed =
           (await documentIndexer.indexDocument({
             accountId: grant.accountId,
             workspaceId,
             documentId: document.id,
+            authorityKind: document.authorityKind,
+            authorityWorkspaceId: document.authorityWorkspaceId,
+            authoritySubjectId: document.authoritySubjectId,
           })) ?? queued;
         if (indexed.status === "ready") {
           await recordWorkspaceUsage(deps, {
@@ -236,44 +280,52 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!base) {
       throw new HTTPException(404, { message: "document base not found" });
     }
-    return c.json({
-      results: await searchDocuments(
-        db,
-        {
-          workspaceId,
-          baseIds: [base.id],
-          query: payload.query,
-          limit: payload.limit,
-          mode: payload.mode,
-          sourceKinds: payload.sourceKinds,
-          aclTags: payload.aclTags,
-          access: { viewerSubjectId: grant.subjectId },
-        },
-        getDocumentServices(),
-      ),
-    });
+    return c.json(
+      DocumentSearchResponse.parse({
+        results: await searchEffectiveDocuments(
+          db,
+          {
+            accountId: grant.accountId,
+            workspaceId,
+            baseIds: [base.id],
+            query: payload.query,
+            limit: payload.limit,
+            mode: payload.mode,
+            sourceKinds: payload.sourceKinds,
+            aclTags: payload.aclTags,
+            initiatingSubjectId: grant.subjectId,
+            surface: "human",
+          },
+          getDocumentServices(),
+        ),
+      }),
+    );
   });
 
   app.post("/v1/workspaces/:workspaceId/knowledge/search", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "documents:search");
     const payload = await parseDocumentSearchRequest(c, "invalid knowledge search request");
-    return c.json({
-      results: await searchDocuments(
-        db,
-        {
-          workspaceId,
-          query: payload.query,
-          baseIds: payload.baseIds,
-          limit: payload.limit,
-          mode: payload.mode,
-          sourceKinds: payload.sourceKinds,
-          aclTags: payload.aclTags,
-          access: { viewerSubjectId: grant.subjectId },
-        },
-        getDocumentServices(),
-      ),
-    });
+    return c.json(
+      DocumentSearchResponse.parse({
+        results: await searchEffectiveDocuments(
+          db,
+          {
+            accountId: grant.accountId,
+            workspaceId,
+            query: payload.query,
+            baseIds: payload.baseIds,
+            limit: payload.limit,
+            mode: payload.mode,
+            sourceKinds: payload.sourceKinds,
+            aclTags: payload.aclTags,
+            initiatingSubjectId: grant.subjectId,
+            surface: "human",
+          },
+          getDocumentServices(),
+        ),
+      }),
+    );
   });
 
   // Knowledge drop: raw text or an uploaded file, no metadata required. Lands
@@ -282,7 +334,8 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
   // curation is disabled.
   app.post("/v1/workspaces/:workspaceId/knowledge/drops", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:manage");
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "documents:manage");
+    const { grant } = access;
     if (!objectStorage) {
       throw new HTTPException(503, { message: "object storage is not configured" });
     }
@@ -293,6 +346,11 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
       quantity: 0,
     });
     const payload = CreateKnowledgeDropRequest.parse(await c.req.json());
+    const organizationAuthorityGranted =
+      access.accountGrant?.permissions.includes("account:admin") === true;
+    if (payload.authorityKind === "organization" && !organizationAuthorityGranted) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
     try {
       let fileId: string;
       if (payload.text !== undefined) {
@@ -353,12 +411,15 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
       const document = await addDocumentToBase(db, {
         fileId,
         ...(payload.title ? { title: payload.title } : {}),
+        ...(payload.authorityKind ? { authorityKind: payload.authorityKind } : {}),
         ...(payload.visibility ? { visibility: payload.visibility } : {}),
         ...(payload.agentAccess !== undefined ? { agentAccess: payload.agentAccess } : {}),
         accountId: grant.accountId,
         workspaceId,
         baseId: defaultBase.id,
         createdBy: grant.subjectId,
+        initiatingSubjectId: grant.subjectId,
+        organizationAuthorityGranted,
         curationStatus: "pending",
         access: { viewerSubjectId: grant.subjectId },
       });
@@ -371,6 +432,9 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
               accountId: grant.accountId,
               workspaceId,
               documentId: document.id,
+              authorityKind: document.authorityKind,
+              authorityWorkspaceId: document.authorityWorkspaceId,
+              authoritySubjectId: document.authoritySubjectId,
             })) ?? document);
       if (indexed.status === "ready") {
         await recordWorkspaceUsage(deps, {
@@ -397,7 +461,14 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
   // Apply a curation suggestion (no body target) or move to an explicit base.
   app.post("/v1/workspaces/:workspaceId/documents/:documentId/move", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:manage");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "documents:manage",
+    );
+    const { grant } = authorization;
+    const organizationAuthorityGranted = hasAccountAdminAuthority(authorization);
     const payload = MoveDocumentRequest.parse(await c.req.json().catch(() => ({})));
     try {
       const document = await getDocument(db, workspaceId, c.req.param("documentId"), {
@@ -406,6 +477,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
       if (!document) {
         throw new HTTPException(404, { message: "document not found" });
       }
+      requireOrganizationDocumentAuthority(document.authorityKind, organizationAuthorityGranted);
       return c.json(
         Document.parse(
           await moveDocumentToBase(db, {
@@ -413,6 +485,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
             workspaceId,
             documentId: document.id,
             targetBaseId: payload.targetBaseId ?? null,
+            organizationAuthorityGranted,
             access: { viewerSubjectId: grant.subjectId },
           }),
         ),
@@ -565,7 +638,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
       grant.accountId,
       workspaceId,
       getDocumentServices(),
-      { createdBySessionId: sessionId, viewerSubjectId: grant.subjectId },
+      { createdBySessionId: sessionId, initiatingSubjectId: grant.subjectId },
     );
     await server.connect(transport);
     return await transport.handleRequest(c.req.raw);
@@ -591,6 +664,9 @@ function dropFilename(preferred: string | undefined): string {
 
 function documentHttpException(error: unknown): HTTPException {
   const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("organization document") && message.includes("exact account authority")) {
+    return new HTTPException(403, { message: "missing permission: account:admin" });
+  }
   if (message.includes("not found")) {
     return new HTTPException(404, { message });
   }
@@ -615,3 +691,18 @@ function documentHttpException(error: unknown): HTTPException {
   }
   return new HTTPException(500, { message });
 }
+
+function hasAccountAdminAuthority(
+  authorization: Awaited<ReturnType<typeof requireAccessGrantAuthorization>>,
+): boolean {
+  return authorization.accountGrant?.permissions.includes("account:admin") === true;
+}
+
+function requireOrganizationDocumentAuthority(
+  authorityKind: string,
+  organizationAuthorityGranted: boolean,
+): void {
+  if (authorityKind === "organization" && !organizationAuthorityGranted) {
+    throw new HTTPException(403, { message: "missing permission: account:admin" });
+  }
+}

package/src/routes/workspace-instruction-policies.ts

@@ -1,6 +1,8 @@
+import { randomUUID } from "node:crypto";
 import {
   ActivateWorkspaceInstructionPolicyRequest,
   CreateWorkspaceInstructionPolicyDraftRequest,
+  CreateWorkspaceInstructionPolicyOnboardingProposalRequest,
   ImportLegacyWorkspaceInstructionPolicyDraftRequest,
   RollbackWorkspaceInstructionPolicyRequest,
   WorkspaceInstructionPolicyActivationResponse,
@@ -9,21 +11,35 @@ import {
   WorkspaceInstructionPolicyDiffResponse,
   WorkspaceInstructionPolicyListQuery,
   WorkspaceInstructionPolicyListResponse,
+  WorkspaceInstructionPolicyOnboardingProposal,
+  WorkspaceInstructionPolicyOnboardingProposalConflictResponse,
+  WorkspaceInstructionPolicyOnboardingProposalContentErrorResponse,
+  WorkspaceInstructionPolicyOnboardingProposalListQuery,
+  WorkspaceInstructionPolicyOnboardingProposalListResponse,
+  WorkspaceInstructionPolicyOnboardingProposalStaleResponse,
+  WorkspaceInstructionPolicyOperationReuseResponse,
   WorkspaceInstructionPolicyRevision,
+  WORKSPACE_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
 } from "@opengeni/contracts";
 import { requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
 import {
   activateWorkspaceInstructionPolicyRevision,
   createWorkspaceInstructionPolicyDraft,
+  createWorkspaceInstructionPolicyOnboardingProposal,
   diffWorkspaceInstructionPolicyRevisions,
   getWorkspaceInstructionPolicyRevision,
   importLegacyWorkspaceInstructionPolicyDraft,
   listWorkspaceInstructionPolicyRevisions,
+  listWorkspaceInstructionPolicyOnboardingProposals,
   rollbackWorkspaceInstructionPolicyRevision,
   WorkspaceInstructionPolicyConflictError,
   WorkspaceInstructionPolicyInvalidOperationError,
   WorkspaceInstructionPolicyLegacyUnavailableError,
   WorkspaceInstructionPolicyNotFoundError,
+  WorkspaceInstructionPolicyOnboardingProposalConflictError,
+  WorkspaceInstructionPolicyOnboardingProposalContentError,
+  WorkspaceInstructionPolicyOnboardingProposalStaleError,
+  WorkspaceInstructionPolicyOperationReuseError,
 } from "@opengeni/db";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
@@ -50,6 +66,46 @@ function policyErrorResponse(context: Context, error: unknown): Response {
       409,
     );
   }
+  if (error instanceof WorkspaceInstructionPolicyOperationReuseError) {
+    return context.json(
+      WorkspaceInstructionPolicyOperationReuseResponse.parse({
+        code: error.code,
+        message: error.message,
+      }),
+      409,
+    );
+  }
+  if (error instanceof WorkspaceInstructionPolicyOnboardingProposalContentError) {
+    return context.json(
+      WorkspaceInstructionPolicyOnboardingProposalContentErrorResponse.parse({
+        code: error.code,
+        message: error.message,
+        maxChars: WORKSPACE_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
+      }),
+      422,
+    );
+  }
+  if (error instanceof WorkspaceInstructionPolicyOnboardingProposalStaleError) {
+    return context.json(
+      WorkspaceInstructionPolicyOnboardingProposalStaleResponse.parse({
+        code: error.code,
+        message: error.message,
+        currentHead: error.currentHead,
+      }),
+      409,
+    );
+  }
+  if (error instanceof WorkspaceInstructionPolicyOnboardingProposalConflictError) {
+    return context.json(
+      WorkspaceInstructionPolicyOnboardingProposalConflictResponse.parse({
+        code: error.code,
+        message: error.message,
+        existingProposalId: error.existingProposalId,
+        existingDraftRevisionId: error.existingDraftRevisionId,
+      }),
+      409,
+    );
+  }
   if (error instanceof WorkspaceInstructionPolicyNotFoundError) {
     return context.json(
       { code: "WORKSPACE_INSTRUCTION_POLICY_NOT_FOUND", message: error.message },
@@ -117,6 +173,7 @@ export function registerWorkspaceInstructionPolicyRoutes(app: Hono, deps: ApiRou
       return context.json(
         WorkspaceInstructionPolicyRevision.parse(
           await createWorkspaceInstructionPolicyDraft(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
             accountId: grant.accountId,
             workspaceId,
             createdBySubjectId: grant.subjectId,
@@ -145,6 +202,7 @@ export function registerWorkspaceInstructionPolicyRoutes(app: Hono, deps: ApiRou
       return context.json(
         WorkspaceInstructionPolicyRevision.parse(
           await importLegacyWorkspaceInstructionPolicyDraft(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
             accountId: grant.accountId,
             workspaceId,
             createdBySubjectId: grant.subjectId,
@@ -158,6 +216,58 @@ export function registerWorkspaceInstructionPolicyRoutes(app: Hono, deps: ApiRou
     }
   });
 
+  app.get(`${base}/onboarding-proposals`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const parsed = WorkspaceInstructionPolicyOnboardingProposalListQuery.safeParse({
+      limit: context.req.query("limit"),
+    });
+    if (!parsed.success) {
+      throw new HTTPException(422, {
+        message: "Invalid workspace instruction-policy onboarding-proposal query",
+      });
+    }
+    return context.json(
+      WorkspaceInstructionPolicyOnboardingProposalListResponse.parse(
+        await listWorkspaceInstructionPolicyOnboardingProposals(deps.db, workspaceId, parsed.data),
+      ),
+    );
+  });
+
+  app.post(`${base}/onboarding-proposals`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:admin");
+    assertBoundedActor(grant.subjectId);
+    const request = await parseBody(
+      context,
+      CreateWorkspaceInstructionPolicyOnboardingProposalRequest,
+    );
+    try {
+      return context.json(
+        WorkspaceInstructionPolicyOnboardingProposal.parse(
+          await createWorkspaceInstructionPolicyOnboardingProposal(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
+            accountId: grant.accountId,
+            workspaceId,
+            createdBySubjectId: grant.subjectId,
+            kind: request.kind,
+            scope: request.scope,
+            roleKey: request.roleKey,
+            content: request.content,
+            sourceId: request.sourceId,
+            sourceVersion: request.sourceVersion,
+            confidenceBps: request.confidenceBps,
+            expectedCurrentRevisionId: request.expectedCurrentRevisionId,
+            expectedActivationVersion: request.expectedActivationVersion,
+          }),
+        ),
+        201,
+      );
+    } catch (error) {
+      return policyErrorResponse(context, error);
+    }
+  });
+
   app.get(`${base}/diff`, async (context) => {
     const workspaceId = context.req.param("workspaceId");
     await requireAccessGrant(context, deps, workspaceId, "workspace:read");
@@ -188,10 +298,14 @@ export function registerWorkspaceInstructionPolicyRoutes(app: Hono, deps: ApiRou
       return context.json(
         WorkspaceInstructionPolicyActivationResponse.parse(
           await rollbackWorkspaceInstructionPolicyRevision(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
             accountId: grant.accountId,
             workspaceId,
             targetRevisionId: request.targetRevisionId,
             expectedCurrentRevisionId: request.expectedCurrentRevisionId,
+            ...(request.expectedActivationVersion === undefined
+              ? {}
+              : { expectedActivationVersion: request.expectedActivationVersion }),
             actorSubjectId: grant.subjectId,
             reason: request.reason,
           }),
@@ -227,10 +341,14 @@ export function registerWorkspaceInstructionPolicyRoutes(app: Hono, deps: ApiRou
       return context.json(
         WorkspaceInstructionPolicyActivationResponse.parse(
           await activateWorkspaceInstructionPolicyRevision(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
             accountId: grant.accountId,
             workspaceId,
             revisionId,
             expectedCurrentRevisionId: request.expectedCurrentRevisionId,
+            ...(request.expectedActivationVersion === undefined
+              ? {}
+              : { expectedActivationVersion: request.expectedActivationVersion }),
             actorSubjectId: grant.subjectId,
             reason: request.reason,
           }),