@opengeni/api-router 0.17.0 → 0.21.0

package/dist/{chunk-MWBF2GXL.js → chunk-5EEC7Q6C.js}

@@ -17,9 +17,10 @@ import {
 } from "@opengeni/contracts";
 import {
   createDocumentServices,
+  getDocument as getDocument2,
   indexDocumentNow
 } from "@opengeni/documents";
-import { dbSql, getWorkspace as getWorkspace5 } from "@opengeni/db";
+import { dbSql, getWorkspace as getWorkspace5, rlsContextForWorkspace } from "@opengeni/db";
 import { createObservability } from "@opengeni/observability";
 import { createObjectStorage } from "@opengeni/storage";
 import { WebStandardStreamableHTTPServerTransport as WebStandardStreamableHTTPServerTransport3 } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
@@ -10948,6 +10949,8 @@ import {
 import {
   GOOGLE_DRIVE_PROVIDER_DOMAIN as GOOGLE_DRIVE_PROVIDER_DOMAIN2,
   GoogleDriveConnectionMetadata as GoogleDriveConnectionMetadata2,
+  GoogleDriveDisconnectRequest,
+  GoogleDriveLifecycleActionRequest,
   GoogleDriveOAuthStartRequest,
   GoogleDriveOAuthStartResponse as GoogleDriveOAuthStartResponse2
 } from "@opengeni/contracts/google-drive";
@@ -10985,6 +10988,7 @@ import {
   GOOGLE_DRIVE_READONLY_SCOPE,
   GoogleDriveBrowseItem,
   GoogleDriveBrowseResponse,
+  GoogleDriveConnectionLifecycle,
   GoogleDriveConnectionMetadata,
   GoogleDriveOAuthStartResponse,
   SaveGoogleDriveSourceRequest,
@@ -10994,13 +10998,17 @@ import {
 import { hasPermission as hasPermission7, requireEnvironmentEncryption as requireEnvironmentEncryption3 } from "@opengeni/core";
 import {
   buildConnectionTokenResolver as buildConnectionTokenResolver3,
+  ConnectionDisconnectGenerationError,
+  ConnectionDisconnectIdempotencyError,
   consumeIntegrationOAuthStateNonce as consumeIntegrationOAuthStateNonce3,
   createConnection as createConnection2,
   decryptEnvironmentValue as decryptEnvironmentValue3,
+  disconnectConnectionIdempotently,
   encryptEnvironmentValue as encryptEnvironmentValue4,
   getConnectionMetadata as getConnectionMetadata2,
   getWorkspaceGrant as getWorkspaceGrant4,
   loadConnectionCredentialForBroker,
+  transitionConnectionState,
   updateConnection as updateConnection2
 } from "@opengeni/db";
 import { createSignedState as createSignedState5, readSignedState as readSignedState4 } from "@opengeni/github";
@@ -11014,6 +11022,12 @@ var GOOGLE_RESPONSE_MAX_BYTES = 2 * 1024 * 1024;
 var GOOGLE_REQUEST_TIMEOUT_MS = 1e4;
 var GOOGLE_DRIVE_PAGE_SIZE = 100;
 var GOOGLE_DRIVE_RETURN_PATH = (workspaceId) => `/workspaces/${workspaceId}/capabilities`;
+var GOOGLE_DRIVE_RECONSENT_ERROR_CODES = /* @__PURE__ */ new Set([
+  "appNotAuthorizedToFile",
+  "authError",
+  "insufficientFilePermissions",
+  "insufficientPermissions"
+]);
 async function startGoogleDriveOAuth(deps, input) {
   const google = requireGoogleDriveSettings(deps.settings);
   const existing = input.payload.connectionId ? await getConnectionMetadata2(
@@ -11156,6 +11170,7 @@ async function completeGoogleDriveOAuthCallback(deps, input) {
       googleDisplayName: identity.displayName,
       verifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
       accessMode: scopeDecision.accessMode,
+      lifecycle: googleDriveLifecycle("active"),
       ...previousMetadata?.selectedSources ? { selectedSources: previousMetadata.selectedSources } : previousMetadata?.selectedSource ? { selectedSources: [previousMetadata.selectedSource] } : {}
     });
     const connection = existing ? await updateConnection2(deps.db, {
@@ -11201,6 +11216,101 @@ async function completeGoogleDriveOAuthCallback(deps, input) {
     };
   }
 }
+async function transitionGoogleDriveLifecycle(deps, input) {
+  const existing = await getConnectionMetadata2(
+    deps.db,
+    input.workspaceId,
+    input.connectionId,
+    input.subjectId
+  );
+  if (!existing) {
+    throw new HTTPException10(404, { message: "Google Drive connection not found" });
+  }
+  const metadata = requireGoogleDriveConnection(existing, input.subjectId);
+  const lifecycle = effectiveGoogleDriveLifecycle(existing, metadata);
+  const targetState = input.payload.action === "pause" ? "paused" : "active";
+  if (existing.status === "active" && lifecycle.state === targetState) {
+    return existing;
+  }
+  if (existing.status === "revoked") {
+    throw new HTTPException10(409, {
+      message: "Google Drive is disconnected; connect it again instead"
+    });
+  }
+  if (input.payload.action === "pause" && lifecycle.state !== "active") {
+    throw new HTTPException10(409, {
+      message: "Google Drive must be reconnected before it can be paused"
+    });
+  }
+  if (input.payload.action === "resume" && lifecycle.state !== "paused") {
+    throw new HTTPException10(409, {
+      message: "Google Drive must be reconnected or re-consented before it can resume"
+    });
+  }
+  if (existing.status !== "active" || existing.version !== input.payload.expectedVersion) {
+    throw new HTTPException10(409, { message: "Google Drive connection changed; try again" });
+  }
+  const updated = await transitionConnectionState(deps.db, {
+    workspaceId: input.workspaceId,
+    connectionId: existing.id,
+    visibleToSubjectId: input.subjectId,
+    expectedVersion: existing.version,
+    status: "active",
+    metadata: GoogleDriveConnectionMetadata.parse({
+      ...metadata,
+      lifecycle: googleDriveLifecycle(targetState)
+    }),
+    lastError: null,
+    updatedBySubjectId: input.subjectId
+  });
+  if (!updated) {
+    const converged = await getConnectionMetadata2(
+      deps.db,
+      input.workspaceId,
+      input.connectionId,
+      input.subjectId
+    );
+    if (converged?.status === "active") {
+      const convergedMetadata = requireGoogleDriveConnection(converged, input.subjectId);
+      if (effectiveGoogleDriveLifecycle(converged, convergedMetadata).state === targetState) {
+        return converged;
+      }
+    }
+    throw new HTTPException10(409, { message: "Google Drive connection changed; try again" });
+  }
+  return updated;
+}
+async function disconnectGoogleDrive(deps, input) {
+  const metadata = requireGoogleDriveConnection(input.connection, input.subjectId);
+  try {
+    return await disconnectConnectionIdempotently(deps.db, {
+      accountId: input.connection.accountId,
+      workspaceId: input.workspaceId,
+      subjectId: input.subjectId,
+      connectionId: input.connection.id,
+      expectedVersion: input.payload.expectedVersion,
+      idempotencyKey: input.payload.idempotencyKey,
+      metadata: GoogleDriveConnectionMetadata.parse({
+        ...metadata,
+        lifecycle: googleDriveLifecycle("disconnected")
+      }),
+      lastError: null,
+      updatedBySubjectId: input.subjectId
+    });
+  } catch (error) {
+    if (error instanceof ConnectionDisconnectIdempotencyError) {
+      throw new HTTPException10(409, {
+        message: "Google Drive disconnect key was already used for another operation"
+      });
+    }
+    if (error instanceof ConnectionDisconnectGenerationError) {
+      throw new HTTPException10(409, {
+        message: "Google Drive connection changed; refresh before disconnecting"
+      });
+    }
+    throw error;
+  }
+}
 async function browseGoogleDrive(deps, input) {
   const connection = await getConnectionMetadata2(
     deps.db,
@@ -11211,7 +11321,7 @@ async function browseGoogleDrive(deps, input) {
   if (!connection) {
     throw new HTTPException10(404, { message: "Google Drive connection not found" });
   }
-  requireGoogleDriveSourceConnection(connection, input.subjectId);
+  await requireGoogleDriveSourceConnection(deps, connection, input.subjectId);
   const parentId = validDriveId(input.parentId, "parentId");
   const currentItem = await resolveGoogleDriveBoundaryItem(deps, {
     workspaceId: input.workspaceId,
@@ -11272,7 +11382,7 @@ async function saveGoogleDriveSource(deps, input) {
   if (!existing) {
     throw new HTTPException10(404, { message: "Google Drive connection not found" });
   }
-  requireGoogleDriveSourceConnection(existing, input.subjectId);
+  await requireGoogleDriveSourceConnection(deps, existing, input.subjectId);
   const verifiedSources = [];
   for (const source of payload.sources) {
     const sourceId = validDriveId(source.id, "source.id");
@@ -11295,8 +11405,8 @@ async function saveGoogleDriveSource(deps, input) {
     input.connectionId,
     input.subjectId
   ) ?? existing;
-  const latestMetadata = requireGoogleDriveSourceConnection(latest, input.subjectId);
-  const updated = await updateConnection2(deps.db, {
+  const latestMetadata = await requireGoogleDriveSourceConnection(deps, latest, input.subjectId);
+  const updated = await transitionConnectionState(deps.db, {
     workspaceId: input.workspaceId,
     connectionId: latest.id,
     visibleToSubjectId: input.subjectId,
@@ -11407,11 +11517,60 @@ function requireGoogleDriveConnection(connection, subjectId) {
   }
   return parsed.data;
 }
-function requireGoogleDriveSourceConnection(connection, subjectId) {
+function googleDriveLifecycle(state) {
+  return GoogleDriveConnectionLifecycle.parse({
+    state,
+    recoverable: state !== "app_removed",
+    observedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+function effectiveGoogleDriveLifecycle(connection, metadata) {
+  if (metadata.lifecycle) return metadata.lifecycle;
+  if (connection.status === "revoked") return googleDriveLifecycle("disconnected");
+  if (connection.status === "active") return googleDriveLifecycle("active");
+  return googleDriveLifecycle("reconnect_required");
+}
+async function transitionGoogleDriveConnectionLifecycle(deps, connection, subjectId, lifecycle, status, lastError) {
   const metadata = requireGoogleDriveConnection(connection, subjectId);
+  if (connection.status === status && metadata.lifecycle?.state === lifecycle.state && metadata.lifecycle.recoverable === lifecycle.recoverable) {
+    return connection;
+  }
+  return await transitionConnectionState(deps.db, {
+    workspaceId: connection.workspaceId,
+    connectionId: connection.id,
+    visibleToSubjectId: subjectId,
+    expectedVersion: connection.version,
+    status,
+    metadata: GoogleDriveConnectionMetadata.parse({ ...metadata, lifecycle }),
+    lastError,
+    updatedBySubjectId: subjectId
+  });
+}
+async function requireGoogleDriveSourceConnection(deps, connection, subjectId) {
+  const metadata = requireGoogleDriveConnection(connection, subjectId);
+  const lifecycle = effectiveGoogleDriveLifecycle(connection, metadata);
+  if (connection.status === "revoked") {
+    throw new HTTPException10(409, { message: "Google Drive is disconnected" });
+  }
+  if (lifecycle.state === "paused") {
+    throw new HTTPException10(409, { message: "Google Drive is paused" });
+  }
+  if (connection.status !== "active" || lifecycle.state !== "active") {
+    throw new HTTPException10(401, {
+      message: lifecycle.state === "reconsent_required" ? "Google Drive needs permission re-consent" : lifecycle.state === "app_removed" ? "Google Drive app access is unavailable" : "Google Drive needs to be reconnected"
+    });
+  }
   if (!googleDriveScopesAllowCapability(connection.grantedScopes, "recursive_source_sync")) {
+    await transitionGoogleDriveConnectionLifecycle(
+      deps,
+      connection,
+      subjectId,
+      googleDriveLifecycle("reconsent_required"),
+      "needs_reauth",
+      "google_drive_reconsent_required"
+    );
     throw new HTTPException10(401, {
-      message: "Google Drive needs to be reconnected with selected-source read access"
+      message: "Google Drive needs permission re-consent for selected-source read access"
     });
   }
   return metadata;
@@ -11522,8 +11681,93 @@ async function verifyGoogleDriveIdentity(accessToken, fetchImpl) {
     displayName: optionalString(user.displayName)
   };
 }
+function googleDriveRefreshFailureLifecycle(failure) {
+  const code = failure.oauthErrorCode?.toLowerCase() ?? null;
+  if (code === "invalid_client" || code === "unauthorized_client") {
+    return {
+      lifecycle: googleDriveLifecycle("app_removed"),
+      status: "error",
+      lastError: "google_drive_app_removed"
+    };
+  }
+  if (code === "invalid_scope" || code === "insufficient_scope") {
+    return {
+      lifecycle: googleDriveLifecycle("reconsent_required"),
+      status: "needs_reauth",
+      lastError: "google_drive_reconsent_required"
+    };
+  }
+  if (code === "invalid_grant") {
+    return {
+      lifecycle: googleDriveLifecycle("token_revoked"),
+      status: "needs_reauth",
+      lastError: "google_drive_token_revoked"
+    };
+  }
+  return {
+    lifecycle: googleDriveLifecycle("reconnect_required"),
+    status: "needs_reauth",
+    lastError: "google_drive_reconnect_required"
+  };
+}
+async function transitionGoogleDrivePermanentRefreshFailure(deps, failure) {
+  if (failure.providerDomain !== GOOGLE_DRIVE_PROVIDER_DOMAIN || !failure.subjectId) {
+    return false;
+  }
+  const connection = await getConnectionMetadata2(
+    deps.db,
+    failure.workspaceId,
+    failure.connectionId,
+    failure.subjectId
+  );
+  if (!connection || connection.version !== failure.connectionVersion) {
+    return true;
+  }
+  const transition = googleDriveRefreshFailureLifecycle(failure);
+  await transitionGoogleDriveConnectionLifecycle(
+    deps,
+    connection,
+    failure.subjectId,
+    transition.lifecycle,
+    transition.status,
+    transition.lastError
+  );
+  return true;
+}
+async function transitionGoogleDriveProviderResponseFailure(deps, input) {
+  const latest = await getConnectionMetadata2(
+    deps.db,
+    input.workspaceId,
+    input.connectionId,
+    input.subjectId
+  );
+  if (!latest || latest.version !== input.connectionVersion || latest.status !== "active") {
+    return;
+  }
+  await transitionGoogleDriveConnectionLifecycle(
+    deps,
+    latest,
+    input.subjectId,
+    input.lifecycle,
+    input.status,
+    input.lastError
+  );
+}
 async function googleDriveApiRequest(deps, input) {
-  const resolver = buildConnectionTokenResolver3(deps.db, deps.settings);
+  const current = await getConnectionMetadata2(
+    deps.db,
+    input.workspaceId,
+    input.connectionId,
+    input.subjectId
+  );
+  if (!current) {
+    throw new HTTPException10(404, { message: "Google Drive connection not found" });
+  }
+  await requireGoogleDriveSourceConnection(deps, current, input.subjectId);
+  const resolver = buildConnectionTokenResolver3(deps.db, deps.settings, void 0, {
+    ...deps.googleDriveFetch ? { refreshTransport: { fetchImpl: deps.googleDriveFetch } } : {},
+    transitionPermanentRefreshFailure: async (failure) => await transitionGoogleDrivePermanentRefreshFailure(deps, failure)
+  });
   const resolve = async (forceRefresh) => await resolver({
     workspaceId: input.workspaceId,
     subjectId: input.subjectId,
@@ -11542,6 +11786,10 @@ async function googleDriveApiRequest(deps, input) {
   if (credential.status !== "ok") {
     throw new HTTPException10(401, { message: "Google Drive needs to be reconnected" });
   }
+  let providerConnectionVersion = credential.connectionVersion;
+  if (providerConnectionVersion === void 0) {
+    throw new Error("Google Drive credential resolver omitted the connection version");
+  }
   const fetchImpl = deps.googleDriveFetch ?? fetch;
   let response = await providerFetch(fetchImpl, input.url, {
     headers: { ...credential.headers, accept: "application/json" }
@@ -11552,14 +11800,45 @@ async function googleDriveApiRequest(deps, input) {
     if (credential.status !== "ok") {
       throw new HTTPException10(401, { message: "Google Drive needs to be reconnected" });
     }
+    providerConnectionVersion = credential.connectionVersion;
+    if (providerConnectionVersion === void 0) {
+      throw new Error("Google Drive credential resolver omitted the connection version");
+    }
     response = await providerFetch(fetchImpl, input.url, {
       headers: { ...credential.headers, accept: "application/json" }
     });
   }
   if (!response.ok) {
-    await response.body?.cancel().catch(() => void 0);
+    if (response.status === 401) {
+      await response.body?.cancel().catch(() => void 0);
+      await transitionGoogleDriveProviderResponseFailure(deps, {
+        workspaceId: input.workspaceId,
+        subjectId: input.subjectId,
+        connectionId: input.connectionId,
+        connectionVersion: providerConnectionVersion,
+        lifecycle: googleDriveLifecycle("reconnect_required"),
+        status: "needs_reauth",
+        lastError: "google_drive_reconnect_required"
+      });
+      throw new HTTPException10(401, { message: "Google Drive needs to be reconnected" });
+    }
+    const providerErrorCode = response.status === 403 ? await readGoogleDriveProviderErrorCode(response) : null;
+    if (response.status !== 403) {
+      await response.body?.cancel().catch(() => void 0);
+    }
+    if (response.status === 403 && providerErrorCode && GOOGLE_DRIVE_RECONSENT_ERROR_CODES.has(providerErrorCode)) {
+      await transitionGoogleDriveProviderResponseFailure(deps, {
+        workspaceId: input.workspaceId,
+        subjectId: input.subjectId,
+        connectionId: input.connectionId,
+        connectionVersion: providerConnectionVersion,
+        lifecycle: googleDriveLifecycle("reconsent_required"),
+        status: "needs_reauth",
+        lastError: "google_drive_reconsent_required"
+      });
+    }
     throw new HTTPException10(response.status === 403 ? 403 : 502, {
-      message: response.status === 403 ? "Google Drive denied metadata access; reconnect and approve the requested scope" : "Google Drive metadata request failed"
+      message: response.status === 403 ? "Google Drive denied metadata access; re-consent may be required" : "Google Drive metadata request failed"
     });
   }
   return await readResponseJsonBounded5(response, GOOGLE_RESPONSE_MAX_BYTES, input.label);
@@ -11575,6 +11854,24 @@ async function providerFetch(fetchImpl, url, init) {
     throw new HTTPException10(502, { message: "Google Drive is temporarily unavailable" });
   }
 }
+async function readGoogleDriveProviderErrorCode(response) {
+  try {
+    const payload = objectRecord(
+      await readResponseJsonBounded5(
+        response,
+        GOOGLE_RESPONSE_MAX_BYTES,
+        "Google Drive error response"
+      )
+    );
+    const error = objectRecord(payload.error);
+    const first = Array.isArray(error.errors) ? objectRecord(error.errors[0]) : {};
+    const code = optionalString(first.reason) ?? optionalString(error.status);
+    return code && /^[A-Za-z0-9_.-]{1,64}$/.test(code) ? code : null;
+  } catch {
+    await response.body?.cancel().catch(() => void 0);
+    return null;
+  }
+}
 function parseDriveItem(value) {
   const item = objectRecord(value);
   const id = optionalString(item.id);
@@ -11864,6 +12161,28 @@ function registerConnectionRoutes(app, deps) {
     });
     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 requireAccessGrant3(c, deps, workspaceId, "connections:write");
+      const parsed = GoogleDriveLifecycleActionRequest.safeParse(await c.req.json());
+      if (!parsed.success) {
+        throw new HTTPException11(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) => {
@@ -11980,7 +12299,22 @@ function registerConnectionRoutes(app, deps) {
     if (!existing) {
       throw new HTTPException11(404, { message: "connection not found" });
     }
-    const connection = isOpenGeniSlackBotConnection2(existing) ? await revokeConnectionWithSlackBotSuccessAudit(db, {
+    const isGoogleDrive = existing.subjectId === grant.subjectId && existing.providerDomain === GOOGLE_DRIVE_PROVIDER_DOMAIN2 && existing.kind === "oauth2" && GoogleDriveConnectionMetadata2.safeParse(existing.metadata).success;
+    const googleDriveDisconnect = isGoogleDrive ? GoogleDriveDisconnectRequest.safeParse(await c.req.json().catch(() => null)) : null;
+    if (googleDriveDisconnect && !googleDriveDisconnect.success) {
+      throw new HTTPException11(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,
+      connection: existing,
+      payload: googleDriveDisconnect.data
+    }) : isOpenGeniSlackBotConnection2(existing) ? await revokeConnectionWithSlackBotSuccessAudit(db, {
       accountId: grant.accountId,
       workspaceId,
       subjectId: grant.subjectId,
@@ -11989,7 +12323,7 @@ function registerConnectionRoutes(app, deps) {
       credentialRole: OPENGENI_SLACK_BOT_CREDENTIAL_ROLE2,
       credentialLabel: OPENGENI_SLACK_BOT_CREDENTIAL_LABEL2,
       slackTeamId: openGeniSlackBotMetadata2(existing.metadata).slackTeamId
-    }) : await revokeConnection(db, workspaceId, connectionId, grant.subjectId);
+    }) : await revokeConnection(db, workspaceId, connectionId, grant.subjectId, existing.version);
     if (!connection) {
       throw new HTTPException11(409, { message: "connection changed during disconnect; try again" });
     }
@@ -12326,6 +12660,7 @@ import {
   Document,
   DocumentBase,
   DocumentSearchRequest,
+  DocumentSearchResponse as DocumentSearchResponse2,
   KnowledgeMemory,
   KnowledgeMemorySearchRequest,
   MoveDocumentRequest,
@@ -12354,18 +12689,19 @@ import {
   listDocuments,
   moveDocumentToBase,
   queueDocumentForReindex,
-  searchDocuments as searchDocuments2
+  searchEffectiveDocuments as searchEffectiveDocuments2
 } from "@opengeni/documents";
 import { WebStandardStreamableHTTPServerTransport as WebStandardStreamableHTTPServerTransport2 } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { HTTPException as HTTPException13 } from "hono/http-exception";
-import { requireAccessGrant as requireAccessGrant5 } from "@opengeni/core";
+import { requireAccessGrant as requireAccessGrant5, requireAccessGrantAuthorization } from "@opengeni/core";
 import { recordWorkspaceUsage as recordWorkspaceUsage3, requireLimit as requireLimit3 } from "@opengeni/core";
 
 // src/mcp/documents.ts
+import { DocumentSearchResponse } from "@opengeni/contracts";
 import {
   getDocumentChunk,
   listDocumentBases,
-  searchDocuments
+  searchEffectiveDocuments
 } from "@opengeni/documents";
 import { createKnowledgeMemory, listKnowledgeMemories } from "@opengeni/db";
 import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -12397,14 +12733,14 @@ var SourceRefSchema = z2.object({
   title: z2.string().min(1).optional(),
   metadata: z2.record(z2.string(), z2.unknown()).optional()
 });
-function buildDocumentsMcpServer(db, accountId, workspaceId, documentServices, options = {}) {
+function buildDocumentsMcpServer(db, accountId, workspaceId, documentServices, options) {
   const server = new McpServer2({
     name: "opengeni-documents",
     version: "1.0.0"
   });
   const agentAccess = {
     agentOnly: true,
-    ...options.viewerSubjectId ? { viewerSubjectId: options.viewerSubjectId } : {}
+    viewerSubjectId: options.initiatingSubjectId
   };
   server.registerTool(
     "list_document_bases",
@@ -12422,15 +12758,31 @@ function buildDocumentsMcpServer(db, accountId, workspaceId, documentServices, o
       description: "Search indexed documents with hybrid, vector, or keyword retrieval.",
       inputSchema: SearchInputSchema
     },
-    async (input) => searchContent(db, workspaceId, documentServices, input, agentAccess)
+    async (input) => searchContent(
+      db,
+      accountId,
+      workspaceId,
+      documentServices,
+      input,
+      options.initiatingSubjectId,
+      false
+    )
   );
   server.registerTool(
     "knowledge_search",
     {
-      description: "Search company knowledge sources with optional base, source-kind, ACL, and retrieval-mode filters.",
+      description: "Search the effective authorized organization, current-workspace, and immutable initiating-user personal document scope. Authorization is applied before ranking and every result retains source and authority provenance.",
       inputSchema: SearchInputSchema
     },
-    async (input) => searchContent(db, workspaceId, documentServices, input, agentAccess)
+    async (input) => searchContent(
+      db,
+      accountId,
+      workspaceId,
+      documentServices,
+      input,
+      options.initiatingSubjectId,
+      true
+    )
   );
   server.registerTool(
     "fetch_document_chunk",
@@ -12441,7 +12793,7 @@ function buildDocumentsMcpServer(db, accountId, workspaceId, documentServices, o
       }
     },
     async ({ chunkId }) => {
-      const found = await getDocumentChunk(db, workspaceId, chunkId, agentAccess);
+      const found = await getDocumentChunk(db, accountId, workspaceId, chunkId, agentAccess);
       return {
         content: [
           { type: "text", text: found ? JSON.stringify(found) : `chunk not found: ${chunkId}` }
@@ -12459,7 +12811,7 @@ function buildDocumentsMcpServer(db, accountId, workspaceId, documentServices, o
       }
     },
     async ({ chunkId }) => {
-      const found = await getDocumentChunk(db, workspaceId, chunkId, agentAccess);
+      const found = await getDocumentChunk(db, accountId, workspaceId, chunkId, agentAccess);
       return {
         content: [
           { type: "text", text: found ? JSON.stringify(found) : `chunk not found: ${chunkId}` }
@@ -12536,27 +12888,28 @@ function buildDocumentsMcpServer(db, accountId, workspaceId, documentServices, o
   );
   return server;
 }
-async function searchContent(db, workspaceId, documentServices, input, access) {
+async function searchContent(db, accountId, workspaceId, documentServices, input, initiatingSubjectId, wrapResponse) {
+  const results = await searchEffectiveDocuments(
+    db,
+    {
+      accountId,
+      workspaceId,
+      query: input.query,
+      ...input.baseIds ? { baseIds: input.baseIds } : {},
+      ...input.limit ? { limit: input.limit } : {},
+      ...input.mode ? { mode: input.mode } : {},
+      ...input.sourceKinds ? { sourceKinds: input.sourceKinds } : {},
+      ...input.aclTags ? { aclTags: input.aclTags } : {},
+      initiatingSubjectId,
+      surface: "agent"
+    },
+    documentServices
+  );
   return {
     content: [
       {
         type: "text",
-        text: JSON.stringify(
-          await searchDocuments(
-            db,
-            {
-              workspaceId,
-              query: input.query,
-              ...input.baseIds ? { baseIds: input.baseIds } : {},
-              ...input.limit ? { limit: input.limit } : {},
-              ...input.mode ? { mode: input.mode } : {},
-              ...input.sourceKinds ? { sourceKinds: input.sourceKinds } : {},
-              ...input.aclTags ? { aclTags: input.aclTags } : {},
-              access
-            },
-            documentServices
-          )
-        )
+        text: JSON.stringify(wrapResponse ? DocumentSearchResponse.parse({ results }) : results)
       }
     ]
   };
@@ -13047,7 +13400,8 @@ function registerDocumentRoutes(app, deps) {
   });
   app.post("/v1/workspaces/:workspaceId/document-bases/:baseId/documents", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:manage");
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "documents:manage");
+    const { grant } = access;
     if (!objectStorage) {
       throw new HTTPException13(503, { message: "object storage is not configured" });
     }
@@ -13058,6 +13412,10 @@ function registerDocumentRoutes(app, deps) {
       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 HTTPException13(403, { message: "missing permission: account:admin" });
+    }
     try {
       const document = await addDocumentToBase(db, {
         ...payload,
@@ -13065,13 +13423,18 @@ function registerDocumentRoutes(app, deps) {
         workspaceId,
         baseId: c.req.param("baseId"),
         createdBy: grant.subjectId,
+        initiatingSubjectId: grant.subjectId,
+        organizationAuthorityGranted,
         access: { viewerSubjectId: grant.subjectId }
       });
       const wasCreated = document.status === "queued" && document.chunkCount === 0 && document.error === null;
       const indexed = document.status === "ready" ? document : await documentIndexer.indexDocument({
         accountId: grant.accountId,
         workspaceId,
-        documentId: document.id
+        documentId: document.id,
+        authorityKind: document.authorityKind,
+        authorityWorkspaceId: document.authorityWorkspaceId,
+        authoritySubjectId: document.authoritySubjectId
       }) ?? document;
       if (indexed.status === "ready") {
         await recordWorkspaceUsage3(deps, {
@@ -13104,13 +13467,28 @@ function registerDocumentRoutes(app, deps) {
     "/v1/workspaces/:workspaceId/document-bases/:baseId/documents/:documentId",
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant5(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 HTTPException13(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);
@@ -13126,7 +13504,14 @@ function registerDocumentRoutes(app, deps) {
     "/v1/workspaces/:workspaceId/document-bases/:baseId/documents/:documentId/reindex",
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant5(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 HTTPException13(503, { message: "object storage is not configured" });
       }
@@ -13143,19 +13528,29 @@ function registerDocumentRoutes(app, deps) {
         if (!document) {
           throw new HTTPException13(404, { message: "document not found" });
         }
+        requireOrganizationDocumentAuthority(document.authorityKind, organizationAuthorityGranted);
         if (document.status !== "failed") {
           throw new HTTPException13(422, { message: "only failed documents can be retried" });
         }
         if (document.baseId !== c.req.param("baseId")) {
           throw new HTTPException13(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
+          documentId: document.id,
+          authorityKind: document.authorityKind,
+          authorityWorkspaceId: document.authorityWorkspaceId,
+          authoritySubjectId: document.authoritySubjectId
         }) ?? queued;
         if (indexed.status === "ready") {
           await recordWorkspaceUsage3(deps, {
@@ -13187,47 +13582,56 @@ function registerDocumentRoutes(app, deps) {
     if (!base) {
       throw new HTTPException13(404, { message: "document base not found" });
     }
-    return c.json({
-      results: await searchDocuments2(
-        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(
+      DocumentSearchResponse2.parse({
+        results: await searchEffectiveDocuments2(
+          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 requireAccessGrant5(c, deps, workspaceId, "documents:search");
     const payload = await parseDocumentSearchRequest(c, "invalid knowledge search request");
-    return c.json({
-      results: await searchDocuments2(
-        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(
+      DocumentSearchResponse2.parse({
+        results: await searchEffectiveDocuments2(
+          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()
+        )
+      })
+    );
   });
   app.post("/v1/workspaces/:workspaceId/knowledge/drops", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant5(c, deps, workspaceId, "documents:manage");
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "documents:manage");
+    const { grant } = access;
     if (!objectStorage) {
       throw new HTTPException13(503, { message: "object storage is not configured" });
     }
@@ -13238,6 +13642,10 @@ function registerDocumentRoutes(app, deps) {
       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 HTTPException13(403, { message: "missing permission: account:admin" });
+    }
     try {
       let fileId;
       if (payload.text !== void 0) {
@@ -13298,12 +13706,15 @@ function registerDocumentRoutes(app, deps) {
       const document = await addDocumentToBase(db, {
         fileId,
         ...payload.title ? { title: payload.title } : {},
+        ...payload.authorityKind ? { authorityKind: payload.authorityKind } : {},
         ...payload.visibility ? { visibility: payload.visibility } : {},
         ...payload.agentAccess !== void 0 ? { agentAccess: payload.agentAccess } : {},
         accountId: grant.accountId,
         workspaceId,
         baseId: defaultBase.id,
         createdBy: grant.subjectId,
+        initiatingSubjectId: grant.subjectId,
+        organizationAuthorityGranted,
         curationStatus: "pending",
         access: { viewerSubjectId: grant.subjectId }
       });
@@ -13311,7 +13722,10 @@ function registerDocumentRoutes(app, deps) {
       const indexed = document.status === "ready" ? document : await documentIndexer.indexDocument({
         accountId: grant.accountId,
         workspaceId,
-        documentId: document.id
+        documentId: document.id,
+        authorityKind: document.authorityKind,
+        authorityWorkspaceId: document.authorityWorkspaceId,
+        authoritySubjectId: document.authoritySubjectId
       }) ?? document;
       if (indexed.status === "ready") {
         await recordWorkspaceUsage3(deps, {
@@ -13336,7 +13750,14 @@ function registerDocumentRoutes(app, deps) {
   });
   app.post("/v1/workspaces/:workspaceId/documents/:documentId/move", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant5(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"), {
@@ -13345,6 +13766,7 @@ function registerDocumentRoutes(app, deps) {
       if (!document) {
         throw new HTTPException13(404, { message: "document not found" });
       }
+      requireOrganizationDocumentAuthority(document.authorityKind, organizationAuthorityGranted);
       return c.json(
         Document.parse(
           await moveDocumentToBase(db, {
@@ -13352,6 +13774,7 @@ function registerDocumentRoutes(app, deps) {
             workspaceId,
             documentId: document.id,
             targetBaseId: payload.targetBaseId ?? null,
+            organizationAuthorityGranted,
             access: { viewerSubjectId: grant.subjectId }
           })
         )
@@ -13488,7 +13911,7 @@ function registerDocumentRoutes(app, deps) {
       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);
@@ -13507,6 +13930,9 @@ function dropFilename(preferred) {
 }
 function documentHttpException(error) {
   const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("organization document") && message.includes("exact account authority")) {
+    return new HTTPException13(403, { message: "missing permission: account:admin" });
+  }
   if (message.includes("not found")) {
     return new HTTPException13(404, { message });
   }
@@ -13524,6 +13950,14 @@ function documentHttpException(error) {
   }
   return new HTTPException13(500, { message });
 }
+function hasAccountAdminAuthority(authorization) {
+  return authorization.accountGrant?.permissions.includes("account:admin") === true;
+}
+function requireOrganizationDocumentAuthority(authorityKind, organizationAuthorityGranted) {
+  if (authorityKind === "organization" && !organizationAuthorityGranted) {
+    throw new HTTPException13(403, { message: "missing permission: account:admin" });
+  }
+}
 
 // src/routes/enrollments.ts
 import {
@@ -16679,6 +17113,10 @@ The initial conversation items are authoritative context from the current sessio
 
 Live context wrapped in <session_user_message> is an authoritative user message already routed to the current session. A status of queued_for_execution means it is waiting behind existing work; accepted_for_execution means it is next with no existing work ahead; accepted_for_steering means it was given priority as a change of direction, while any prior work may still be yielding. Incorporate it immediately as conversation context, but never delegate it again or treat the wrapper metadata as user-authored text.
 
+Live context wrapped in <session_human_input_request> means current work is paused for the user's answer. Preserve the exact question meaning and options. Ask one question at a time when useful. The user may answer in the visible form or answer conversationally. If the user answers conversationally, create exactly one delegation containing the relevant question and the user's answer so the session agent can continue with complete context. If the user changes direction instead, delegate the new direction normally. Do not claim work resumed until session context confirms it.
+
+Live context wrapped in <session_human_input_response> is the authoritative outcome of that pending question. An answered or skipped response came through the structured session UI and is already routed; incorporate it, never delegate it again, and acknowledge briefly only if useful. An expired or cancelled response means the question is no longer active.
+
 Live session updates may describe work that started before this realtime conversation, work sent directly by the user, or work delegated during an earlier realtime connection. Treat those updates as part of this same session even when they have no current delegation identity.
 
 ## Backend use
@@ -21426,9 +21864,11 @@ function requireAccountPermission(context, accountId, permission) {
 }
 
 // src/routes/workspace-instruction-policies.ts
+import { randomUUID } from "crypto";
 import {
   ActivateWorkspaceInstructionPolicyRequest,
   CreateWorkspaceInstructionPolicyDraftRequest,
+  CreateWorkspaceInstructionPolicyOnboardingProposalRequest,
   ImportLegacyWorkspaceInstructionPolicyDraftRequest,
   RollbackWorkspaceInstructionPolicyRequest,
   WorkspaceInstructionPolicyActivationResponse,
@@ -21437,21 +21877,35 @@ import {
   WorkspaceInstructionPolicyDiffResponse,
   WorkspaceInstructionPolicyListQuery,
   WorkspaceInstructionPolicyListResponse,
-  WorkspaceInstructionPolicyRevision
+  WorkspaceInstructionPolicyOnboardingProposal,
+  WorkspaceInstructionPolicyOnboardingProposalConflictResponse,
+  WorkspaceInstructionPolicyOnboardingProposalContentErrorResponse,
+  WorkspaceInstructionPolicyOnboardingProposalListQuery,
+  WorkspaceInstructionPolicyOnboardingProposalListResponse,
+  WorkspaceInstructionPolicyOnboardingProposalStaleResponse,
+  WorkspaceInstructionPolicyOperationReuseResponse,
+  WorkspaceInstructionPolicyRevision,
+  WORKSPACE_INSTRUCTION_POLICY_CONTENT_MAX_CHARS
 } from "@opengeni/contracts";
 import { requireAccessGrant as requireAccessGrant17 } from "@opengeni/core";
 import {
   activateWorkspaceInstructionPolicyRevision,
   createWorkspaceInstructionPolicyDraft,
+  createWorkspaceInstructionPolicyOnboardingProposal,
   diffWorkspaceInstructionPolicyRevisions,
   getWorkspaceInstructionPolicyRevision,
   importLegacyWorkspaceInstructionPolicyDraft,
   listWorkspaceInstructionPolicyRevisions,
+  listWorkspaceInstructionPolicyOnboardingProposals,
   rollbackWorkspaceInstructionPolicyRevision,
   WorkspaceInstructionPolicyConflictError,
   WorkspaceInstructionPolicyInvalidOperationError,
   WorkspaceInstructionPolicyLegacyUnavailableError,
-  WorkspaceInstructionPolicyNotFoundError
+  WorkspaceInstructionPolicyNotFoundError,
+  WorkspaceInstructionPolicyOnboardingProposalConflictError,
+  WorkspaceInstructionPolicyOnboardingProposalContentError,
+  WorkspaceInstructionPolicyOnboardingProposalStaleError,
+  WorkspaceInstructionPolicyOperationReuseError
 } from "@opengeni/db";
 import { HTTPException as HTTPException27 } from "hono/http-exception";
 import { z as z7 } from "zod";
@@ -21474,6 +21928,46 @@ function policyErrorResponse(context, error) {
       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 },
@@ -21536,6 +22030,7 @@ function registerWorkspaceInstructionPolicyRoutes(app, deps) {
       return context.json(
         WorkspaceInstructionPolicyRevision.parse(
           await createWorkspaceInstructionPolicyDraft(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
             accountId: grant.accountId,
             workspaceId,
             createdBySubjectId: grant.subjectId,
@@ -21563,6 +22058,7 @@ function registerWorkspaceInstructionPolicyRoutes(app, deps) {
       return context.json(
         WorkspaceInstructionPolicyRevision.parse(
           await importLegacyWorkspaceInstructionPolicyDraft(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
             accountId: grant.accountId,
             workspaceId,
             createdBySubjectId: grant.subjectId,
@@ -21575,6 +22071,56 @@ function registerWorkspaceInstructionPolicyRoutes(app, deps) {
       return policyErrorResponse(context, error);
     }
   });
+  app.get(`${base}/onboarding-proposals`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    await requireAccessGrant17(context, deps, workspaceId, "workspace:read");
+    const parsed = WorkspaceInstructionPolicyOnboardingProposalListQuery.safeParse({
+      limit: context.req.query("limit")
+    });
+    if (!parsed.success) {
+      throw new HTTPException27(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 requireAccessGrant17(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 requireAccessGrant17(context, deps, workspaceId, "workspace:read");
@@ -21604,10 +22150,12 @@ function registerWorkspaceInstructionPolicyRoutes(app, deps) {
       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 === void 0 ? {} : { expectedActivationVersion: request.expectedActivationVersion },
             actorSubjectId: grant.subjectId,
             reason: request.reason
           })
@@ -21641,10 +22189,12 @@ function registerWorkspaceInstructionPolicyRoutes(app, deps) {
       return context.json(
         WorkspaceInstructionPolicyActivationResponse.parse(
           await activateWorkspaceInstructionPolicyRevision(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
             accountId: grant.accountId,
             workspaceId,
             revisionId,
             expectedCurrentRevisionId: request.expectedCurrentRevisionId,
+            ...request.expectedActivationVersion === void 0 ? {} : { expectedActivationVersion: request.expectedActivationVersion },
             actorSubjectId: grant.subjectId,
             reason: request.reason
           })
@@ -21661,11 +22211,14 @@ import {
   WORKSPACE_STATE_MAX_BASES as WORKSPACE_STATE_MAX_BASES2,
   WORKSPACE_STATE_MAX_TOPICS as WORKSPACE_STATE_MAX_TOPICS2,
   WORKSPACE_STATE_TOPIC_MAX_CHARS as WORKSPACE_STATE_TOPIC_MAX_CHARS2,
+  WorkspaceStateQuery,
   WorkspaceStateResponse as WorkspaceStateResponse2
 } from "@opengeni/contracts";
 import { hasPermission as hasPermission12, requireAccessGrant as requireAccessGrant18 } from "@opengeni/core";
 import {
   getWorkspace as getWorkspace2,
+  getCurrentPreferenceRegistryGovernanceMetadata,
+  getWorkspaceStateAcceptedAttemptGovernance,
   listWorkspaceStateMemoryRecords,
   listWorkspaceInstructionPolicyRevisions as listWorkspaceInstructionPolicyRevisions2
 } from "@opengeni/db";
@@ -21673,6 +22226,7 @@ import { getDocumentInventory } from "@opengeni/documents";
 import { HTTPException as HTTPException28 } from "hono/http-exception";
 
 // src/workspace-state-projection.ts
+import { createHash as createHash8 } from "crypto";
 import {
   KnowledgeMemoryKind,
   KnowledgeMemoryStatus,
@@ -21685,6 +22239,140 @@ import {
   WORKSPACE_STATE_TOPIC_MAX_CHARS,
   WorkspaceStateResponse
 } from "@opengeni/contracts";
+function hashIdentities(values) {
+  return createHash8("sha256").update(values.join("\n"), "utf8").digest("hex");
+}
+function policyTargetKey(value) {
+  return `${value.kind}:${value.scope}:${value.roleKey ?? ""}`;
+}
+function policyTargetKeysForRole(policyRole) {
+  const keys = /* @__PURE__ */ new Set(["charter:global:", "policy:global:"]);
+  if (policyRole !== null) keys.add(`policy:role:${policyRole}`);
+  return keys;
+}
+function policyIdentity(value) {
+  return `${policyTargetKey(value)}:${value.revisionId}:${value.contentHash}:${value.activationVersion}`;
+}
+function preferenceIdentity(value) {
+  return `${value.scope}:${value.id}:${value.revisionId}:${value.contentHash}:${value.activeVersion}`;
+}
+function classifyIdentityDrift(snapshotIdentities, currentIdentities, snapshotKeys, currentKeys) {
+  if (snapshotIdentities.join("\n") === currentIdentities.join("\n")) return "identical";
+  return snapshotKeys.join("\n") === currentKeys.join("\n") ? "superseded" : "changed";
+}
+function overallDriftStatus(policy, preferences) {
+  for (const status of ["unavailable", "truncated", "missing", "changed", "superseded"]) {
+    if (policy === status || preferences === status) return status;
+  }
+  return "identical";
+}
+function attemptGovernanceProjection(input) {
+  const governance = input.attemptGovernance ?? null;
+  if (governance === null) return { status: "not_requested" };
+  if (governance.status === "unavailable") {
+    return {
+      status: "unavailable",
+      reason: "attempt_not_found_or_not_authorized",
+      driftStatus: "unavailable"
+    };
+  }
+  const policySnapshot = governance.policySnapshot;
+  let policyStatus = "missing";
+  let policySnapshotHash = null;
+  let policyCurrentHash = null;
+  let policySnapshotTargetCount = 0;
+  let policyCurrentTargetCount = 0;
+  if (policySnapshot) {
+    const snapshotEntries = [...policySnapshot.entries].sort(
+      (left, right) => policyTargetKey(left).localeCompare(policyTargetKey(right))
+    );
+    const snapshotKeys = snapshotEntries.map(policyTargetKey);
+    const relevantTargetKeys = policyTargetKeysForRole(policySnapshot.policyRole);
+    const currentEntries = input.policies.activeHeads.filter((head) => relevantTargetKeys.has(policyTargetKey(head))).sort((left, right) => policyTargetKey(left).localeCompare(policyTargetKey(right)));
+    const snapshotIdentities = snapshotEntries.map(policyIdentity);
+    const currentIdentities = currentEntries.map(policyIdentity);
+    const currentKeys = currentEntries.map(policyTargetKey);
+    policyStatus = classifyIdentityDrift(
+      snapshotIdentities,
+      currentIdentities,
+      snapshotKeys,
+      currentKeys
+    );
+    policySnapshotHash = hashIdentities(snapshotIdentities);
+    policyCurrentHash = hashIdentities(currentIdentities);
+    policySnapshotTargetCount = snapshotEntries.length;
+    policyCurrentTargetCount = currentEntries.length;
+  }
+  const preferenceSnapshot = governance.preferenceSnapshot;
+  const currentPreferences = [...governance.currentPreferences.descriptors].sort(
+    (left, right) => preferenceIdentity(left).localeCompare(preferenceIdentity(right))
+  );
+  let preferenceStatus = "missing";
+  let preferenceSnapshotHash = null;
+  const currentPreferenceIdentities = currentPreferences.map(preferenceIdentity);
+  const currentPreferenceHash = hashIdentities(currentPreferenceIdentities);
+  let snapshotPreferenceCount = 0;
+  let snapshotPreferenceTruncated = false;
+  if (preferenceSnapshot) {
+    const snapshotPreferences = [...preferenceSnapshot.descriptors].sort(
+      (left, right) => preferenceIdentity(left).localeCompare(preferenceIdentity(right))
+    );
+    const snapshotPreferenceIdentities = snapshotPreferences.map(preferenceIdentity);
+    const snapshotPreferenceKeys = snapshotPreferences.map((descriptor) => descriptor.id).sort();
+    const currentPreferenceKeys = currentPreferences.map((descriptor) => descriptor.id).sort();
+    preferenceSnapshotHash = hashIdentities(snapshotPreferenceIdentities);
+    snapshotPreferenceCount = snapshotPreferences.length;
+    snapshotPreferenceTruncated = preferenceSnapshot.truncated;
+    preferenceStatus = preferenceSnapshot.truncated || governance.currentPreferences.truncated ? "truncated" : classifyIdentityDrift(
+      snapshotPreferenceIdentities,
+      currentPreferenceIdentities,
+      snapshotPreferenceKeys,
+      currentPreferenceKeys
+    );
+  }
+  return {
+    status: "available",
+    attemptId: governance.attemptId,
+    executionGeneration: governance.executionGeneration,
+    acceptedAt: governance.acceptedAt,
+    policySnapshot: policySnapshot ? {
+      status: "available",
+      id: policySnapshot.id,
+      createdAt: policySnapshot.createdAt,
+      entryHash: policySnapshot.entryHash,
+      policyRole: policySnapshot.policyRole,
+      roleSource: policySnapshot.roleSource,
+      entries: policySnapshot.entries
+    } : { status: "missing" },
+    preferenceSnapshot: preferenceSnapshot ? {
+      status: "available",
+      id: preferenceSnapshot.id,
+      createdAt: preferenceSnapshot.createdAt,
+      descriptorHash: preferenceSnapshot.descriptorHash,
+      descriptorCount: preferenceSnapshot.descriptors.length,
+      truncated: preferenceSnapshot.truncated
+    } : { status: "missing" },
+    drift: {
+      overall: overallDriftStatus(policyStatus, preferenceStatus),
+      policy: {
+        status: policyStatus,
+        snapshotHash: policySnapshotHash,
+        currentHash: policyCurrentHash,
+        snapshotTargetCount: policySnapshotTargetCount,
+        currentTargetCount: policyCurrentTargetCount
+      },
+      preferences: {
+        status: preferenceStatus,
+        snapshotHash: preferenceSnapshotHash,
+        currentHash: currentPreferenceHash,
+        snapshotDescriptorCount: snapshotPreferenceCount,
+        currentDescriptorCount: currentPreferences.length,
+        snapshotTruncated: snapshotPreferenceTruncated,
+        currentTruncated: governance.currentPreferences.truncated
+      }
+    }
+  };
+}
 function emptyMemoryStatusCounts() {
   return Object.fromEntries(
     KnowledgeMemoryStatus.options.map((status) => [status, 0])
@@ -21856,10 +22544,7 @@ function projectWorkspaceState(input) {
     generatedAt: input.generatedAt,
     truth: {
       current: { source: "read_time_projection", capturedAt: input.generatedAt },
-      policySnapshot: {
-        status: "not_captured",
-        reason: "workspace_instruction_policy_snapshot_not_implemented"
-      }
+      attemptGovernance: attemptGovernanceProjection(input)
     },
     policy: policyProjection(input),
     knowledge: input.knowledge ? availableKnowledgeProjection(input.knowledge) : {
@@ -21874,10 +22559,11 @@ function projectWorkspaceState(input) {
 function registerWorkspaceStateRoutes(app, deps) {
   app.get("/v1/workspaces/:workspaceId/workspace-state", async (context) => {
     const workspaceId = context.req.param("workspaceId");
+    const query = WorkspaceStateQuery.parse(context.req.query());
     const grant = await requireAccessGrant18(context, deps, workspaceId, "workspace:read");
     const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
     const canInspectKnowledge = hasPermission12(grant.permissions, "documents:search");
-    const [workspace, policies, knowledge] = await Promise.all([
+    const [workspace, policies, knowledge, attemptGovernance] = await Promise.all([
       getWorkspace2(deps.db, workspaceId),
       listWorkspaceInstructionPolicyRevisions2(deps.db, workspaceId, { limit: 1 }),
       canInspectKnowledge ? (async () => {
@@ -21891,7 +22577,43 @@ function registerWorkspaceStateRoutes(app, deps) {
           listWorkspaceStateMemoryRecords(deps.db, workspaceId)
         ]);
         return { documents, memories };
-      })() : Promise.resolve(null)
+      })() : Promise.resolve(null),
+      query.attemptId ? getWorkspaceStateAcceptedAttemptGovernance(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        subjectId: grant.subjectId,
+        attemptId: query.attemptId
+      }).then(async (snapshot) => {
+        if (!snapshot) return { status: "unavailable" };
+        const currentPreferences = await getCurrentPreferenceRegistryGovernanceMetadata(
+          deps.db,
+          {
+            workspaceId,
+            subjectId: grant.subjectId
+          }
+        );
+        return {
+          status: "available",
+          attemptId: snapshot.attemptId,
+          executionGeneration: snapshot.executionGeneration,
+          acceptedAt: snapshot.acceptedAt,
+          policySnapshot: snapshot.policySnapshot,
+          preferenceSnapshot: snapshot.preferenceSnapshot ? {
+            id: snapshot.preferenceSnapshot.id,
+            descriptorHash: snapshot.preferenceSnapshot.descriptorHash,
+            descriptors: snapshot.preferenceSnapshot.descriptors.map((descriptor) => ({
+              id: descriptor.id,
+              revisionId: descriptor.revisionId,
+              contentHash: descriptor.contentHash,
+              activeVersion: descriptor.activeVersion,
+              scope: descriptor.scope
+            })),
+            truncated: snapshot.preferenceSnapshot.truncated,
+            createdAt: snapshot.preferenceSnapshot.createdAt
+          } : null,
+          currentPreferences
+        };
+      }) : Promise.resolve(null)
     ]);
     if (!workspace) {
       throw new HTTPException28(404, { message: "workspace not found" });
@@ -21904,7 +22626,8 @@ function registerWorkspaceStateRoutes(app, deps) {
           generatedAt,
           workspaceAgentInstructions: workspace.agentInstructions,
           policies,
-          knowledge
+          knowledge,
+          attemptGovernance
         })
       )
     );
@@ -21912,7 +22635,7 @@ function registerWorkspaceStateRoutes(app, deps) {
 }
 
 // src/routes/workspace-artifacts.ts
-import { createHash as createHash8 } from "crypto";
+import { createHash as createHash9 } from "crypto";
 import {
   CreateWorkspaceArtifactRequest,
   PublishWorkspaceArtifactVersionRequest,
@@ -21981,7 +22704,7 @@ function errorResponse(context, error) {
 }
 function contentMetadata(workspaceId, html) {
   const bytes = encoder2.encode(html);
-  const sha256 = createHash8("sha256").update(bytes).digest("hex");
+  const sha256 = createHash9("sha256").update(bytes).digest("hex");
   return {
     bytes,
     contentSha256: sha256,
@@ -22007,7 +22730,7 @@ function prepareHtml(deps, workspaceId, html) {
 }
 function provenance(subjectId, idempotencyKey) {
   return {
-    operationKey: `subject:${createHash8("sha256").update(`${subjectId}:${idempotencyKey}`).digest("hex")}`,
+    operationKey: `subject:${createHash9("sha256").update(`${subjectId}:${idempotencyKey}`).digest("hex")}`,
     actorSubjectId: subjectId,
     sourceSessionId: null,
     sourceTurnId: null,
@@ -22098,7 +22821,7 @@ function registerWorkspaceArtifactRoutes(app, deps) {
       );
       const object5 = await deps.objectStorage.getObjectBytes(ref.contentKey);
       if (!object5) throw new HTTPException29(503, { message: "Artifact content is unavailable" });
-      const actualHash = createHash8("sha256").update(object5.bytes).digest("hex");
+      const actualHash = createHash9("sha256").update(object5.bytes).digest("hex");
       if (actualHash !== ref.version.contentSha256) {
         throw new HTTPException29(503, { message: "Artifact content failed integrity verification" });
       }
@@ -22192,7 +22915,7 @@ import {
 import {
   hasPermission as hasPermission13,
   requireAccessGrant as requireAccessGrant20,
-  requireAccessGrantAuthorization
+  requireAccessGrantAuthorization as requireAccessGrantAuthorization2
 } from "@opengeni/core";
 import {
   activatePreferenceRegistryRevision,
@@ -22340,7 +23063,7 @@ function registerPreferenceRegistryRoutes(app, deps) {
   });
   app.post(`${base}/proposals`, async (context) => {
     const workspaceId = context.req.param("workspaceId");
-    const access = await requireAccessGrantAuthorization(
+    const access = await requireAccessGrantAuthorization2(
       context,
       deps,
       workspaceId,
@@ -22420,7 +23143,7 @@ function registerPreferenceRegistryRoutes(app, deps) {
   });
   app.post(`${base}/:preferenceId/activate`, async (context) => {
     const workspaceId = context.req.param("workspaceId");
-    const access = await requireAccessGrantAuthorization(
+    const access = await requireAccessGrantAuthorization2(
       context,
       deps,
       workspaceId,
@@ -22449,7 +23172,7 @@ function registerPreferenceRegistryRoutes(app, deps) {
   });
   app.post(`${base}/:preferenceId/correct`, async (context) => {
     const workspaceId = context.req.param("workspaceId");
-    const access = await requireAccessGrantAuthorization(
+    const access = await requireAccessGrantAuthorization2(
       context,
       deps,
       workspaceId,
@@ -22478,7 +23201,7 @@ function registerPreferenceRegistryRoutes(app, deps) {
   });
   app.post(`${base}/:preferenceId/scope`, async (context) => {
     const workspaceId = context.req.param("workspaceId");
-    const access = await requireAccessGrantAuthorization(
+    const access = await requireAccessGrantAuthorization2(
       context,
       deps,
       workspaceId,
@@ -22507,7 +23230,7 @@ function registerPreferenceRegistryRoutes(app, deps) {
   });
   app.post(`${base}/:preferenceId/deactivate`, async (context) => {
     const workspaceId = context.req.param("workspaceId");
-    const access = await requireAccessGrantAuthorization(
+    const access = await requireAccessGrantAuthorization2(
       context,
       deps,
       workspaceId,
@@ -22536,7 +23259,7 @@ function registerPreferenceRegistryRoutes(app, deps) {
   });
   app.post(`${base}/:preferenceId/supersede`, async (context) => {
     const workspaceId = context.req.param("workspaceId");
-    const access = await requireAccessGrantAuthorization(
+    const access = await requireAccessGrantAuthorization2(
       context,
       deps,
       workspaceId,
@@ -22565,7 +23288,7 @@ function registerPreferenceRegistryRoutes(app, deps) {
   });
   app.post(`${base}/:preferenceId/reject`, async (context) => {
     const workspaceId = context.req.param("workspaceId");
-    const access = await requireAccessGrantAuthorization(
+    const access = await requireAccessGrantAuthorization2(
       context,
       deps,
       workspaceId,
@@ -23072,7 +23795,7 @@ async function firstAvailable(providers, context) {
 }
 
 // src/integrations/slack-interactions.ts
-import { createHash as createHash9, createHmac as createHmac2, timingSafeEqual as timingSafeEqual2 } from "crypto";
+import { createHash as createHash10, createHmac as createHmac2, timingSafeEqual as timingSafeEqual2 } from "crypto";
 import {
   DEFAULT_FIRST_PARTY_MCP_TOOLS as DEFAULT_FIRST_PARTY_MCP_TOOLS2,
   hasOpenGeniSlackReactionScope,
@@ -23220,7 +23943,7 @@ function slackReactionInboxEntry(payload, bot, settings) {
   if (!settings.enabled || !event || event.type !== "reaction_added" || item?.type !== "message" || !teamId || !eventId || !userId || userId === bot.botUserId || !reaction || reaction !== settings.emoji || !channelId || !workspaceSlackReactionChannelAllowed(settings, channelId) || !timestamp) {
     return null;
   }
-  const stableReactionIdentity = createHash9("sha256").update([teamId, userId, channelId, timestamp, reaction].join("\n")).digest("hex");
+  const stableReactionIdentity = createHash10("sha256").update([teamId, userId, channelId, timestamp, reaction].join("\n")).digest("hex");
   return {
     providerEventId: eventId,
     providerMessageId: `reaction:${stableReactionIdentity}`,
@@ -24221,7 +24944,7 @@ function slackRouteKey(channelId, threadTs) {
   return `${channelId}:${threadTs}`;
 }
 function deterministicUuid(value) {
-  const bytes = createHash9("sha256").update(value).digest().subarray(0, 16);
+  const bytes = createHash10("sha256").update(value).digest().subarray(0, 16);
   bytes[6] = bytes[6] & 15 | 80;
   bytes[8] = bytes[8] & 63 | 128;
   const hex = bytes.toString("hex");
@@ -24358,14 +25081,27 @@ function createAppComposition(deps) {
     indexDocument: async ({
       accountId,
       workspaceId,
-      documentId
+      documentId,
+      authorityKind,
+      authorityWorkspaceId,
+      authoritySubjectId
     }) => {
       if (!objectStorage) {
         throw new HTTPException33(503, {
           message: "object storage is not configured"
         });
       }
-      return await indexDocumentNow(
+      const context = await rlsContextForWorkspace(deps.db, workspaceId);
+      if (context.accountId !== accountId) {
+        throw new Error("document account/workspace authority mismatch");
+      }
+      const claimedDocument = await getDocument2(deps.db, workspaceId, documentId, {
+        viewerSubjectId: authoritySubjectId
+      });
+      if (!claimedDocument || claimedDocument.authorityKind !== authorityKind || claimedDocument.authorityWorkspaceId !== authorityWorkspaceId || claimedDocument.authoritySubjectId !== authoritySubjectId) {
+        throw new Error("document authority changed before indexing");
+      }
+      const document = await indexDocumentNow(
         deps.db,
         objectStorage,
         workspaceId,
@@ -24380,8 +25116,13 @@ function createAppComposition(deps) {
               quantity: chunkCount
             });
           }
-        }
+        },
+        { viewerSubjectId: authoritySubjectId }
       );
+      if (document.authorityKind !== authorityKind || document.authorityWorkspaceId !== authorityWorkspaceId || document.authoritySubjectId !== authoritySubjectId) {
+        throw new Error("document authority changed before indexing");
+      }
+      return document;
     }
   };
   const sandboxClient = deps.sandboxClient ?? createApiSandboxClient(deps.settings);
@@ -25349,4 +26090,4 @@ export {
   withDefaultEnabledCapabilityMcpTools,
   workflowIdForSession2 as workflowIdForSession
 };
-//# sourceMappingURL=chunk-MWBF2GXL.js.map
+//# sourceMappingURL=chunk-5EEC7Q6C.js.map