@opengeni/api-router 0.30.1 → 1.0.0

package/src/routes/documents.ts

@@ -1,61 +1,101 @@
+import { fileOwnerContextForAccess } from "@opengeni/core";
+import { withSessionRlsActorContext } from "@opengeni/db";
 import {
   AddDocumentRequest,
   CreateKnowledgeDropRequest,
-  CreateKnowledgeMemoryRequest,
   CreateDocumentBaseRequest,
   Document,
+  DocumentAuthorityReclassification,
   DocumentBase,
-  DocumentSearchRequest,
-  DocumentSearchResponse,
-  KnowledgeMemory,
-  KnowledgeMemorySearchRequest,
+  DocumentDefaultCollectionBackfill,
+  DocumentDefaultCollectionBackfillAudit,
+  GetDocumentDefaultCollectionBackfillAuditQuery,
+  FileAsset,
+  FileDownloadUrlResponse,
+  ListDocumentAuthorityReclassificationsQuery,
+  ListDocumentAuthorityReclassificationsResponse,
+  ListDocumentDefaultCollectionBackfillRunsResponse,
+  ListDocumentMigrationAuditQuery,
+  ListOrganizationDocumentAuthorityReclassificationsResponse,
   MoveDocumentRequest,
-  UpdateKnowledgeMemoryRequest,
-  WorkspaceMemorySearchRequest,
-  WorkspaceMemorySearchResponse,
+  ReclassifyDocumentAuthorityRequest,
+  RunDocumentDefaultCollectionBackfillRequest,
 } from "@opengeni/contracts";
-import {
-  completeFileUpload,
-  createFileUpload,
-  createKnowledgeMemory,
-  getKnowledgeMemory,
-  listKnowledgeMemories,
-  updateKnowledgeMemory,
-  searchWorkspaceMemories,
-} from "@opengeni/db";
+import { recordAuditEvent, completeFileUpload, createFileUpload } from "@opengeni/db";
 import {
   addDocumentToBase,
   createDocumentBase,
   deleteDocumentFromBase,
   ensureDefaultBase,
   getDocument,
+  getDocumentOriginalFile,
   getDocumentBase,
+  getDocumentDefaultCollectionBackfillAudit,
+  listAccessibleDocuments,
+  listDocumentAuthorityReclassifications,
+  listDocumentDefaultCollectionBackfillRuns,
   listDocumentBasesEnsuringDefault,
   listDocuments,
+  listOrganizationDocumentAuthorityReclassifications,
   moveDocumentToBase,
   queueDocumentForReindex,
-  searchEffectiveDocuments,
+  reclassifyDocumentAuthority,
+  runDocumentDefaultCollectionBackfill,
 } from "@opengeni/documents";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
-import type { Context, Hono } from "hono";
+import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import {
   requireAccessGrant,
+  requireAccountAdminAuthorizationStamp,
   requireAccessGrantAuthorization,
-  saveWorkspaceMemoryWithSlackPublication,
+  knowledgeContextForAccess,
 } from "@opengeni/core";
 import { recordWorkspaceUsage, requireLimit } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { buildDocumentsMcpServer } from "../mcp/documents";
+import { mcpOAuthAuthenticateHeader, resolveMcpOAuthRouteAccess } from "../mcp-oauth";
+import { withAccessGrantSessionRlsContext } from "../access-grant-rls";
+import {
+  buildWorkspaceToolGatewayMcpServer,
+  prepareMcpOAuthWorkspaceToolGateway,
+} from "../workspace-tool-gateway";
 import { sanitizeFilename } from "./files";
+import { userContentSignedGetUrlOptions } from "../http/user-content";
+import { parseRequestBody, parseRequestJson } from "../http/request-body";
 
 export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
   const { db, objectStorage, documentIndexer, getDocumentServices } = deps;
+  // Document compatibility uploads use the same verified personal file owner as
+  // Files and chat uploads. A delegated subject label never becomes an owner.
+  for (const path of [
+    "/v1/workspaces/:workspaceId/document-bases/*",
+    "/v1/workspaces/:workspaceId/documents/*",
+    "/v1/workspaces/:workspaceId/knowledge/drops",
+  ]) {
+    app.use(path, async (c, next) => {
+      const permission =
+        (c.req.method === "GET" && !c.req.path.includes("/authority-reclassifications")) ||
+        c.req.path.endsWith("/search")
+          ? "documents:search"
+          : "documents:manage";
+      const access = await requireAccessGrantAuthorization(
+        c,
+        deps,
+        c.req.param("workspaceId") ?? "",
+        permission,
+      );
+      return withSessionRlsActorContext(
+        await fileOwnerContextForAccess(deps, access, permission),
+        next,
+      );
+    });
+  }
 
   app.post("/v1/workspaces/:workspaceId/document-bases", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "documents:manage");
-    const payload = CreateDocumentBaseRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, CreateDocumentBaseRequest);
     return c.json(
       DocumentBase.parse(
         await createDocumentBase(db, { ...payload, accountId: grant.accountId, workspaceId }),
@@ -87,6 +127,136 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
     return c.json(DocumentBase.parse(base));
   });
 
+  app.post("/v1/workspaces/:workspaceId/document-default-collection-backfills", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "documents:manage",
+    );
+    if (!hasAccountAdminAuthority(authorization)) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    const accountAdminAuthorization = requireAccountAdminAuthorizationStamp(authorization);
+    const payload = await parseRequestJson(c, RunDocumentDefaultCollectionBackfillRequest);
+    try {
+      return c.json(
+        DocumentDefaultCollectionBackfill.parse(
+          await runDocumentDefaultCollectionBackfill(db, {
+            ...payload,
+            accountId: authorization.grant.accountId,
+            workspaceId,
+            actorSubjectId: authorization.grant.subjectId,
+            accountAdminAuthorization,
+          }),
+        ),
+      );
+    } catch (error) {
+      throw documentHttpException(error);
+    }
+  });
+
+  app.get("/v1/workspaces/:workspaceId/document-default-collection-backfills", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "documents:manage",
+    );
+    if (!hasAccountAdminAuthority(authorization)) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    const query = ListDocumentMigrationAuditQuery.safeParse(c.req.query());
+    if (!query.success) {
+      throw new HTTPException(400, { message: "invalid document migration audit query" });
+    }
+    try {
+      return c.json(
+        ListDocumentDefaultCollectionBackfillRunsResponse.parse(
+          await listDocumentDefaultCollectionBackfillRuns(db, {
+            accountId: authorization.grant.accountId,
+            workspaceId,
+            actorSubjectId: authorization.grant.subjectId,
+            accountAdminAuthorization: requireAccountAdminAuthorizationStamp(authorization),
+            ...query.data,
+          }),
+        ),
+      );
+    } catch (error) {
+      throw documentHttpException(error);
+    }
+  });
+
+  app.get("/v1/workspaces/:workspaceId/document-default-collection-backfills/:runId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "documents:manage",
+    );
+    if (!hasAccountAdminAuthority(authorization)) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    const runId = RunDocumentDefaultCollectionBackfillRequest.shape.runId.safeParse(
+      c.req.param("runId"),
+    );
+    const query = GetDocumentDefaultCollectionBackfillAuditQuery.safeParse(c.req.query());
+    if (!runId.success || !query.success) {
+      throw new HTTPException(400, { message: "invalid document migration audit query" });
+    }
+    try {
+      return c.json(
+        DocumentDefaultCollectionBackfillAudit.parse(
+          await getDocumentDefaultCollectionBackfillAudit(db, {
+            accountId: authorization.grant.accountId,
+            workspaceId,
+            actorSubjectId: authorization.grant.subjectId,
+            accountAdminAuthorization: requireAccountAdminAuthorizationStamp(authorization),
+            runId: runId.data,
+            ...query.data,
+          }),
+        ),
+      );
+    } catch (error) {
+      throw documentHttpException(error);
+    }
+  });
+
+  app.get("/v1/workspaces/:workspaceId/document-authority-reclassifications", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "documents:manage",
+    );
+    if (!hasAccountAdminAuthority(authorization)) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    const query = ListDocumentMigrationAuditQuery.safeParse(c.req.query());
+    if (!query.success) {
+      throw new HTTPException(400, { message: "invalid document migration audit query" });
+    }
+    try {
+      return c.json(
+        ListOrganizationDocumentAuthorityReclassificationsResponse.parse(
+          await listOrganizationDocumentAuthorityReclassifications(db, {
+            accountId: authorization.grant.accountId,
+            workspaceId,
+            actorSubjectId: authorization.grant.subjectId,
+            accountAdminAuthorization: requireAccountAdminAuthorizationStamp(authorization),
+            ...query.data,
+          }),
+        ),
+      );
+    } catch (error) {
+      throw documentHttpException(error);
+    }
+  });
+
   app.post("/v1/workspaces/:workspaceId/document-bases/:baseId/documents", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "documents:manage");
@@ -100,7 +270,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
       action: "document:index",
       quantity: 0,
     });
-    const payload = AddDocumentRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, AddDocumentRequest);
     const organizationAuthorityGranted =
       access.accountGrant?.permissions.includes("account:admin") === true;
     if (payload.authorityKind === "organization" && !organizationAuthorityGranted) {
@@ -130,19 +300,6 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
               authorityWorkspaceId: document.authorityWorkspaceId,
               authoritySubjectId: document.authoritySubjectId,
             })) ?? document);
-      if (indexed.status === "ready") {
-        await recordWorkspaceUsage(deps, {
-          accountId: grant.accountId,
-          workspaceId,
-          subjectId: grant.subjectId,
-          eventType: "document.indexed",
-          quantity: indexed.chunkCount,
-          unit: "chunk",
-          sourceResourceType: "document",
-          sourceResourceId: indexed.id,
-          idempotencyKey: `document.indexed:${workspaceId}:${indexed.id}:${indexed.updatedAt}`,
-        });
-      }
       return c.json(Document.parse(indexed), wasCreated ? 201 : 200);
     } catch (error) {
       throw documentHttpException(error);
@@ -161,6 +318,151 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
   });
 
+  app.get("/v1/workspaces/:workspaceId/documents", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:search");
+    return c.json(
+      (
+        await listAccessibleDocuments(db, workspaceId, {
+          viewerSubjectId: grant.subjectId,
+        })
+      ).map((document) => Document.parse(document)),
+    );
+  });
+
+  app.post(
+    "/v1/workspaces/:workspaceId/documents/:documentId/authority-reclassifications",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const authorization = await requireAccessGrantAuthorization(
+        c,
+        deps,
+        workspaceId,
+        "documents:manage",
+      );
+      const payload = await parseRequestJson(c, ReclassifyDocumentAuthorityRequest);
+      const accountAdminAuthorized = hasAccountAdminAuthority(authorization);
+      const accountAdminAuthorization = accountAdminAuthorized
+        ? requireAccountAdminAuthorizationStamp(authorization)
+        : null;
+      try {
+        const document = await getDocument(db, workspaceId, c.req.param("documentId"), {
+          viewerSubjectId: authorization.grant.subjectId,
+        });
+        if (!document) throw new HTTPException(404, { message: "document not found" });
+        if (
+          (document.authorityKind === "organization" ||
+            payload.targetAuthorityKind === "organization") &&
+          !accountAdminAuthorization
+        ) {
+          throw new HTTPException(403, { message: "missing permission: account:admin" });
+        }
+        return c.json(
+          DocumentAuthorityReclassification.parse(
+            await reclassifyDocumentAuthority(db, {
+              ...payload,
+              accountId: authorization.grant.accountId,
+              workspaceId,
+              documentId: document.id,
+              actorSubjectId: authorization.grant.subjectId,
+              accountAdminAuthorization,
+            }),
+          ),
+        );
+      } catch (error) {
+        if (error instanceof HTTPException) throw error;
+        throw documentHttpException(error);
+      }
+    },
+  );
+
+  app.get(
+    "/v1/workspaces/:workspaceId/documents/:documentId/authority-reclassifications",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "documents:manage");
+      try {
+        const query = ListDocumentAuthorityReclassificationsQuery.parse(c.req.query());
+        return c.json(
+          ListDocumentAuthorityReclassificationsResponse.parse(
+            await listDocumentAuthorityReclassifications(db, {
+              accountId: grant.accountId,
+              workspaceId,
+              documentId: c.req.param("documentId"),
+              actorSubjectId: grant.subjectId,
+              ...query,
+            }),
+          ),
+        );
+      } catch (error) {
+        throw documentHttpException(error);
+      }
+    },
+  );
+
+  app.get("/v1/workspaces/:workspaceId/documents/:documentId/original-file", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:search");
+    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const file = await getDocumentOriginalFile(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      documentId: c.req.param("documentId"),
+      access: { viewerSubjectId: grant.subjectId },
+    });
+    if (!file) {
+      throw new HTTPException(404, { message: "document file not found" });
+    }
+    return c.json(FileAsset.parse(file));
+  });
+
+  app.post(
+    "/v1/workspaces/:workspaceId/documents/:documentId/original-file/download-url",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "documents:search");
+      await requireAccessGrant(c, deps, workspaceId, "files:read");
+      if (!objectStorage) {
+        throw new HTTPException(503, { message: "object storage is not configured" });
+      }
+      const file = await getDocumentOriginalFile(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        documentId: c.req.param("documentId"),
+        access: { viewerSubjectId: grant.subjectId },
+      });
+      if (!file) {
+        throw new HTTPException(404, { message: "document file not found" });
+      }
+      if (file.status !== "ready") {
+        throw new HTTPException(409, { message: `file is ${file.status}` });
+      }
+      const signed = await objectStorage.createGetUrl({
+        key: file.objectKey,
+        ...userContentSignedGetUrlOptions(file.contentType, file.filename),
+      });
+      await recordAuditEvent(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        subjectId: grant.subjectId,
+        action: "file.signed_url.issued",
+        targetType: "workspace_document",
+        targetId: c.req.param("documentId"),
+        metadata: {
+          fileId: file.id,
+          kind: "document_original",
+          expiresAt: signed.expiresAt.toISOString(),
+        },
+      });
+      return c.json(
+        FileDownloadUrlResponse.parse({
+          url: signed.url,
+          expiresAt: signed.expiresAt.toISOString(),
+        }),
+      );
+    },
+  );
+
   app.delete(
     "/v1/workspaces/:workspaceId/document-bases/:baseId/documents/:documentId",
     async (c) => {
@@ -212,7 +514,9 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
       const { grant } = authorization;
       const organizationAuthorityGranted = hasAccountAdminAuthority(authorization);
       if (!objectStorage) {
-        throw new HTTPException(503, { message: "object storage is not configured" });
+        throw new HTTPException(503, {
+          message: "object storage is not configured",
+        });
       }
       await requireLimit(deps, {
         accountId: grant.accountId,
@@ -246,25 +550,14 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
         const indexed =
           (await documentIndexer.indexDocument({
             accountId: grant.accountId,
-            workspaceId,
+            // The requested workspace authorizes the human operation; the
+            // immutable ingestion workspace remains the indexing authority.
+            workspaceId: queued.workspaceId,
             documentId: document.id,
             authorityKind: document.authorityKind,
             authorityWorkspaceId: document.authorityWorkspaceId,
             authoritySubjectId: document.authoritySubjectId,
           })) ?? queued;
-        if (indexed.status === "ready") {
-          await recordWorkspaceUsage(deps, {
-            accountId: grant.accountId,
-            workspaceId,
-            subjectId: grant.subjectId,
-            eventType: "document.indexed",
-            quantity: indexed.chunkCount,
-            unit: "chunk",
-            sourceResourceType: "document",
-            sourceResourceId: indexed.id,
-            idempotencyKey: `document.indexed:${workspaceId}:${indexed.id}:${indexed.updatedAt}`,
-          });
-        }
         return c.json(Document.parse(indexed));
       } catch (error) {
         if (error instanceof HTTPException) {
@@ -275,66 +568,21 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
     },
   );
 
-  app.post("/v1/workspaces/:workspaceId/document-bases/:baseId/search", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:search");
-    const payload = DocumentSearchRequest.parse(await c.req.json());
-    const base = await getDocumentBase(db, workspaceId, c.req.param("baseId"));
-    if (!base) {
-      throw new HTTPException(404, { message: "document base not found" });
-    }
-    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(
-      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(),
-        ),
-      }),
-    );
-  });
+  for (const path of [
+    "/v1/workspaces/:workspaceId/document-bases/:baseId/search",
+    "/v1/workspaces/:workspaceId/knowledge/search",
+  ]) {
+    app.post(path, async (c) => {
+      await requireAccessGrant(c, deps, c.req.param("workspaceId")!, "documents:search");
+      throw new HTTPException(410, {
+        message:
+          "Document search moved to /knowledge/entries/search. Pending Knowledge is available through its review view.",
+      });
+    });
+  }
 
-  // Knowledge drop: raw text or an uploaded file, no metadata required. Lands
-  // in the workspace Default base with curationStatus 'pending'; indexing then
-  // applies the configured curation provider, or leaves it as 'none' when
-  // curation is disabled.
+  // Compatibility upload endpoint. Retained originals and extracted text now
+  // enter canonical Knowledge. Agent findings use ordinary accepted turns.
   app.post("/v1/workspaces/:workspaceId/knowledge/drops", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "documents:manage");
@@ -348,7 +596,16 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
       action: "document:index",
       quantity: 0,
     });
-    const payload = CreateKnowledgeDropRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, CreateKnowledgeDropRequest);
+    const personalFileOwner =
+      payload.authorityKind === "personal"
+        ? (await fileOwnerContextForAccess(deps, access, "documents:manage"))
+            .privateFileOwnerSubjectId
+        : null;
+    if (payload.authorityKind === "personal" && !personalFileOwner)
+      throw new HTTPException(403, {
+        message: "Personal source retention requires verified ownership",
+      });
     const organizationAuthorityGranted =
       access.accountGrant?.permissions.includes("account:admin") === true;
     if (payload.authorityKind === "organization" && !organizationAuthorityGranted) {
@@ -377,6 +634,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
           accountId: grant.accountId,
           workspaceId,
           fileId: newFileId,
+          privateOwnerSubjectId: personalFileOwner ?? null,
           filename,
           safeFilename,
           contentType: "text/plain; charset=utf-8",
@@ -423,7 +681,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
         createdBy: grant.subjectId,
         initiatingSubjectId: grant.subjectId,
         organizationAuthorityGranted,
-        curationStatus: "pending",
+        curationStatus: "none",
         access: { viewerSubjectId: grant.subjectId },
       });
       const wasCreated =
@@ -439,19 +697,6 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
               authorityWorkspaceId: document.authorityWorkspaceId,
               authoritySubjectId: document.authoritySubjectId,
             })) ?? document);
-      if (indexed.status === "ready") {
-        await recordWorkspaceUsage(deps, {
-          accountId: grant.accountId,
-          workspaceId,
-          subjectId: grant.subjectId,
-          eventType: "document.indexed",
-          quantity: indexed.chunkCount,
-          unit: "chunk",
-          sourceResourceType: "document",
-          sourceResourceId: indexed.id,
-          idempotencyKey: `document.indexed:${workspaceId}:${indexed.id}:${indexed.updatedAt}`,
-        });
-      }
       return c.json(Document.parse(indexed), wasCreated ? 201 : 200);
     } catch (error) {
       if (error instanceof HTTPException) {
@@ -472,7 +717,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
     const { grant } = authorization;
     const organizationAuthorityGranted = hasAccountAdminAuthority(authorization);
-    const payload = MoveDocumentRequest.parse(await c.req.json().catch(() => ({})));
+    const payload = parseRequestBody(MoveDocumentRequest, await c.req.json().catch(() => ({})));
     try {
       const document = await getDocument(db, workspaceId, c.req.param("documentId"), {
         viewerSubjectId: grant.subjectId,
@@ -501,180 +746,92 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
     }
   });
 
-  app.get("/v1/workspaces/:workspaceId/knowledge/memories", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "documents:search");
-    const parsed = KnowledgeMemorySearchRequest.safeParse({
-      query: c.req.query("query") || undefined,
-      status: c.req.query("status") || undefined,
-      kind: c.req.query("kind") || undefined,
-      scope: c.req.query("scope") || undefined,
-      limit: c.req.query("limit") ? Number(c.req.query("limit")) : undefined,
+  // Old clients get an explicit cutover response instead of writing to an
+  // invisible second Knowledge store. Historical Memory IDs are entry IDs now.
+  for (const path of [
+    "/v1/workspaces/:workspaceId/knowledge/memories",
+    "/v1/workspaces/:workspaceId/knowledge/memories/*",
+  ]) {
+    app.all(path, async (c) => {
+      await requireAccessGrant(c, deps, c.req.param("workspaceId")!, "documents:search");
+      return c.json(
+        {
+          error: {
+            code: "memory_replaced",
+            message:
+              "Memory has been replaced by Knowledge entries. Use /knowledge/entries and the current SDK Knowledge methods.",
+          },
+        },
+        410,
+      );
     });
-    if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid knowledge memory query parameters" });
-    }
-    return c.json(
-      (await listKnowledgeMemories(db, workspaceId, parsed.data)).map((memory) =>
-        KnowledgeMemory.parse(memory),
-      ),
-    );
-  });
-
-  app.get("/v1/workspaces/:workspaceId/knowledge/memories/:memoryId", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "documents:search");
-    const memory = await getKnowledgeMemory(db, workspaceId, c.req.param("memoryId"));
-    if (!memory) {
-      throw new HTTPException(404, { message: "knowledge memory not found" });
-    }
-    return c.json(KnowledgeMemory.parse(memory));
-  });
-
-  // Hybrid search over the workspace's agent-visible memory (active ∪ approved).
-  // Available regardless of the workspace memory setting (human/audit lane).
-  app.post("/v1/workspaces/:workspaceId/knowledge/memories/search", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "documents:search");
-    const parsed = WorkspaceMemorySearchRequest.safeParse(await c.req.json());
-    if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid workspace memory search request" });
-    }
-    const results = await searchWorkspaceMemories(
-      db,
-      workspaceId,
-      parsed.data,
-      getDocumentServices().embedder,
-    );
-    return c.json(
-      WorkspaceMemorySearchResponse.parse({
-        results: results.map((result) => ({
-          ...result,
-          memory: KnowledgeMemory.parse(result.memory),
-        })),
-      }),
-    );
-  });
+  }
 
-  app.post("/v1/workspaces/:workspaceId/knowledge/memories", async (c) => {
+  app.all("/v1/workspaces/:workspaceId/mcp/docs", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:manage");
-    const parsedBody = CreateKnowledgeMemoryRequest.safeParse(await c.req.json());
-    if (!parsedBody.success) {
-      throw new HTTPException(400, { message: "invalid knowledge memory request" });
+    let oauthAccess: Awaited<ReturnType<typeof resolveMcpOAuthRouteAccess>>;
+    try {
+      oauthAccess = await resolveMcpOAuthRouteAccess(deps, c.req.raw, workspaceId);
+    } catch (error) {
+      if (error instanceof HTTPException && error.status === 401) {
+        c.header("www-authenticate", mcpOAuthAuthenticateHeader(deps, new URL(c.req.url).pathname));
+      }
+      throw error;
     }
-    const payload = parsedBody.data;
-    if (payload.status !== "active" && payload.slackPublication) {
-      throw new HTTPException(400, {
-        message: "Slack publication is available only for active Workspace Memory writes",
+    if (oauthAccess) {
+      return await withAccessGrantSessionRlsContext(deps, oauthAccess.grant, async () => {
+        const prepared = await prepareMcpOAuthWorkspaceToolGateway(
+          deps,
+          oauthAccess.grant,
+          oauthAccess.allowedToolIdentities,
+        );
+        const transport = new WebStandardStreamableHTTPServerTransport({
+          enableJsonResponse: true,
+        });
+        const server = buildWorkspaceToolGatewayMcpServer(
+          prepared,
+          oauthAccess.grant,
+          deps.observability,
+        );
+        try {
+          await server.connect(transport);
+          return await transport.handleRequest(c.req.raw);
+        } finally {
+          await Promise.allSettled([server.close(), prepared.close()]);
+        }
       });
     }
-    // status `active` (the default) is a memory write → route through the single
-    // gate (sanitize + embed + dedup). Explicit proposed/approved/rejected keeps
-    // the legacy curated create.
-    if (payload.status === "active") {
-      try {
-        const result = await saveWorkspaceMemoryWithSlackPublication(
-          db,
-          {
-            accountId: grant.accountId,
-            workspaceId,
-            text: payload.text,
-            kind: payload.kind,
-            confidence: payload.confidence,
-            pinned: payload.pinned,
-            replacesId: payload.replacesId ?? null,
-            metadata: payload.metadata,
-            origin: "human",
-          },
-          payload.slackPublication
-            ? {
-                distribution: payload.slackPublication,
-                actor: {
-                  kind: "human",
-                  subjectId: grant.subjectId,
-                  initiatingHumanSubjectId: grant.subjectId,
-                },
-                ownerLabel: grant.subjectLabel ?? null,
-              }
-            : null,
-          getDocumentServices().embedder,
-        );
-        return c.json(KnowledgeMemory.parse(result.memory), 201);
-      } catch (error) {
-        throw documentHttpException(error);
+    let grant: Awaited<ReturnType<typeof requireAccessGrant>>;
+    try {
+      grant = await requireAccessGrant(c, deps, workspaceId, "documents:search");
+    } catch (error) {
+      if (deps.settings.mcpOauthEnabled && error instanceof HTTPException && error.status === 401) {
+        c.header("www-authenticate", mcpOAuthAuthenticateHeader(deps, new URL(c.req.url).pathname));
       }
+      throw error;
     }
-    return c.json(
-      KnowledgeMemory.parse(
-        await createKnowledgeMemory(db, {
-          ...payload,
-          accountId: grant.accountId,
-          workspaceId,
-        }),
-      ),
-      201,
-    );
-  });
-
-  app.patch("/v1/workspaces/:workspaceId/knowledge/memories/:memoryId", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:manage");
-    const payload = UpdateKnowledgeMemoryRequest.parse(await c.req.json());
-    const reviewedBy =
-      payload.reviewedBy ??
-      (payload.status === "approved" || payload.status === "rejected"
-        ? (grant.subjectLabel ?? grant.subjectId)
-        : undefined);
-    try {
-      return c.json(
-        KnowledgeMemory.parse(
-          await updateKnowledgeMemory(
-            db,
-            workspaceId,
-            c.req.param("memoryId"),
-            {
-              ...payload,
-              ...(reviewedBy ? { reviewedBy } : {}),
-            },
-            getDocumentServices().embedder,
+    return await withAccessGrantSessionRlsContext(deps, grant, async () => {
+      const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
+      const server = buildDocumentsMcpServer(
+        db,
+        grant.accountId,
+        workspaceId,
+        getDocumentServices(),
+        {
+          knowledge: await knowledgeContextForAccess(
+            deps,
+            await requireAccessGrantAuthorization(c, deps, workspaceId, "documents:search"),
+            "documents:search",
           ),
-        ),
+          settings: deps.settings,
+        },
       );
-    } catch (error) {
-      throw documentHttpException(error);
-    }
-  });
-
-  app.all("/v1/workspaces/:workspaceId/mcp/docs", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:search");
-    const sessionId =
-      typeof grant.metadata?.sessionId === "string" ? grant.metadata.sessionId : undefined;
-    const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
-    const server = buildDocumentsMcpServer(
-      db,
-      grant.accountId,
-      workspaceId,
-      getDocumentServices(),
-      { createdBySessionId: sessionId, initiatingSubjectId: grant.subjectId },
-    );
-    await server.connect(transport);
-    return await transport.handleRequest(c.req.raw);
+      await server.connect(transport);
+      return await transport.handleRequest(c.req.raw);
+    });
   });
 }
 
-async function parseDocumentSearchRequest(
-  context: Context,
-  message: string,
-): Promise<DocumentSearchRequest> {
-  const parsed = DocumentSearchRequest.safeParse(await context.req.json().catch(() => null));
-  if (!parsed.success) {
-    throw new HTTPException(422, { message });
-  }
-  return parsed.data;
-}
-
 /** Derive a .txt filename for a raw-text drop from its optional title/filename. */
 function dropFilename(preferred: string | undefined): string {
   const stem = (preferred ?? "").trim() || `note-${new Date().toISOString().slice(0, 10)}`;
@@ -682,16 +839,47 @@ function dropFilename(preferred: string | undefined): string {
 }
 
 function documentHttpException(error: unknown): HTTPException {
-  const message = error instanceof Error ? error.message : String(error);
+  const message = documentDomainErrorMessage(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 });
   }
+  if (message.includes("document Default collection backfill audit run is unavailable")) {
+    return new HTTPException(404, { message });
+  }
   if (message.includes("already exists")) {
     return new HTTPException(409, { message });
   }
+  if (
+    message.includes("operation id was reused") ||
+    message.includes("authority changed before reclassification") ||
+    message.includes("run identity mismatch")
+  ) {
+    return new HTTPException(409, { message });
+  }
+  if (
+    message.includes("reclassification requires") ||
+    message.includes("backfill requires organization administration") ||
+    message.includes("document migration audit requires organization administration") ||
+    message.includes("document migration audit scope is invalid")
+  ) {
+    return new HTTPException(403, { message });
+  }
+  if (
+    message.includes("reclassification input is invalid") ||
+    message.includes("reclassification authority is invalid") ||
+    message.includes("invalid document authority receipt cursor") ||
+    message.includes("document authority receipt limit") ||
+    message.includes("invalid document migration audit cursor") ||
+    message.includes("document migration audit cursor is invalid") ||
+    message.includes("document migration audit limit") ||
+    message.includes("document migration audit authority is incomplete") ||
+    message.includes("document Default collection backfill audit run id is required")
+  ) {
+    return new HTTPException(400, { message });
+  }
   if (message.includes("no suggested base")) {
     return new HTTPException(422, { message });
   }
@@ -711,6 +899,19 @@ function documentHttpException(error: unknown): HTTPException {
   return new HTTPException(500, { message });
 }
 
+function documentDomainErrorMessage(error: unknown): string {
+  let current: unknown = error;
+  let message = error instanceof Error ? error.message : String(error);
+  const seen = new Set<unknown>();
+  while (current && typeof current === "object" && !seen.has(current) && seen.size < 8) {
+    seen.add(current);
+    const record = current as { cause?: unknown; message?: unknown };
+    if (typeof record.message === "string") message = record.message;
+    current = record.cause;
+  }
+  return message;
+}
+
 function hasAccountAdminAuthority(
   authorization: Awaited<ReturnType<typeof requireAccessGrantAuthorization>>,
 ): boolean {