@opengeni/documents 0.2.72 → 0.3.2

package/src/index.ts

@@ -3,6 +3,7 @@ import type {
   AddDocumentRequest,
   CreateDocumentBaseRequest,
   Document,
+  DocumentAuthorityKind,
   DocumentBase,
   DocumentCuration,
   DocumentCurationStatus,
@@ -13,7 +14,15 @@ import type {
   FileAsset,
   KnowledgeSourceKind,
 } from "@opengeni/contracts";
-import { requireFile, withRlsContext, withWorkspaceRls, type Database } from "@opengeni/db";
+import {
+  requireFile,
+  rlsContextForWorkspace,
+  setSubjectRlsContext,
+  withRlsContext,
+  withWorkspaceRls,
+  withWorkspaceSubjectRls,
+  type Database,
+} from "@opengeni/db";
 import * as schema from "@opengeni/db/schema";
 import type { ObjectStorage } from "@opengeni/storage";
 import { LiteParse } from "@llamaindex/liteparse";
@@ -29,6 +38,7 @@ export const DEFAULT_DOCUMENT_CURATION_MODEL = "gpt-4o-mini";
 // Curator input is a preview, not the whole document — enough to name and
 // classify without paying for a full-document prompt on every drop.
 export const DOCUMENT_CURATION_MAX_INPUT_CHARS = 24_000;
+export const DOCUMENT_AUTHORITY_SUBJECT_MAX_BYTES = 1024;
 // A base move is applied automatically only at or above this curator
 // confidence; below it the suggestion is surfaced for human review instead.
 export const DOCUMENT_CURATION_AUTO_FILE_CONFIDENCE = 0.75;
@@ -118,6 +128,12 @@ export type DocumentAccessFilter = {
   agentOnly?: boolean | undefined;
 };
 
+export type DocumentAuthority = {
+  kind: DocumentAuthorityKind;
+  workspaceId: string | null;
+  subjectId: string | null;
+};
+
 export type DocumentInventoryStatusCounts = Record<DocumentStatus, number>;
 export type DocumentInventorySourceKindCounts = Record<KnowledgeSourceKind, number>;
 
@@ -150,6 +166,7 @@ const DOCUMENT_INVENTORY_MAX_TOPIC_LIMIT = 100;
 const DOCUMENT_INVENTORY_MAX_TOPIC_CHARS = 256;
 
 export type DocumentSearchInput = {
+  accountId: string;
   workspaceId: string;
   query: string;
   baseIds?: string[] | undefined;
@@ -160,6 +177,13 @@ export type DocumentSearchInput = {
   access?: DocumentAccessFilter | undefined;
 };
 
+export type EffectiveDocumentSearchInput = Omit<DocumentSearchInput, "access"> & {
+  /** Immutable human subject accepted for the logical request/turn. */
+  initiatingSubjectId: string;
+  /** Agent retrieval additionally enforces documents.agent_access. */
+  surface: "human" | "agent";
+};
+
 export type DocumentIndexHooks = {
   beforeEmbed?: (input: {
     accountId: string;
@@ -637,7 +661,7 @@ export async function getDocumentInventory(
     "topicMaxChars",
   );
 
-  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+  return await withDocumentRls(db, workspaceId, input.access, async (scopedDb) => {
     const [baseTotal] = await scopedDb
       .select({ count: sql<number>`count(*)::int` })
       .from(schema.documentBases)
@@ -646,7 +670,7 @@ export async function getDocumentInventory(
     const baseJoin = and(
       eq(schema.documents.workspaceId, workspaceId),
       eq(schema.documents.baseId, schema.documentBases.id),
-      ...documentAccessConditions(input.access),
+      ...documentAccessConditions(workspaceId, input.access),
     );
     const baseRows = await scopedDb
       .select({
@@ -668,7 +692,7 @@ export async function getDocumentInventory(
 
     const documentWhere = and(
       eq(schema.documents.workspaceId, workspaceId),
-      ...documentAccessConditions(input.access),
+      ...documentAccessConditions(workspaceId, input.access),
     );
     const [summary] = await scopedDb
       .select({
@@ -859,6 +883,8 @@ export async function addDocumentToBase(
     workspaceId: string;
     baseId: string;
     createdBy?: string | null | undefined;
+    initiatingSubjectId?: string | null | undefined;
+    organizationAuthorityGranted?: boolean | undefined;
     curationStatus?: DocumentCurationStatus | undefined;
     access?: DocumentAccessFilter | undefined;
   },
@@ -867,12 +893,27 @@ export async function addDocumentToBase(
     db,
     { accountId: input.accountId, workspaceId: input.workspaceId },
     async (scopedDb) => {
+      const viewerSubjectId = cleanString(input.access?.viewerSubjectId ?? null);
+      const authority = resolveDocumentAuthority({
+        kind: input.authorityKind,
+        legacyVisibility: input.visibility,
+        workspaceId: input.workspaceId,
+        initiatingSubjectId: input.initiatingSubjectId,
+      });
+      if (authority.kind === "organization" && input.organizationAuthorityGranted !== true) {
+        throw new Error("organization document writes require exact account authority");
+      }
+      if (
+        authority.kind === "personal" &&
+        (viewerSubjectId !== authority.subjectId ||
+          cleanString(input.createdBy ?? null) !== authority.subjectId)
+      ) {
+        throw new Error("personal document writes require the exact initiating subject");
+      }
+      if (viewerSubjectId) await setSubjectRlsContext(scopedDb, viewerSubjectId);
       const base = await getDocumentBase(scopedDb, input.workspaceId, input.baseId);
       if (!base) throw new Error(`Document base not found: ${input.baseId}`);
       const file = await requireReadyFile(scopedDb, input.workspaceId, input.fileId);
-      if (input.visibility === "private" && !cleanString(input.createdBy ?? null)) {
-        throw new Error("private documents require a creating subject");
-      }
       const now = new Date();
       const [existing] = await scopedDb
         .select()
@@ -889,6 +930,10 @@ export async function addDocumentToBase(
         if (!documentMatchesAccess(existing, input.access)) {
           throw new Error(`Document not found: ${existing.id}`);
         }
+        assertOrganizationDocumentAuthority(
+          existing.authorityKind,
+          input.organizationAuthorityGranted,
+        );
         // Idempotent re-add: refresh caller-supplied source metadata on the
         // existing row instead of silently discarding it (aclTags especially —
         // a re-add that tightens tags must not be a no-op). Access policy is
@@ -913,7 +958,7 @@ export async function addDocumentToBase(
             and(
               eq(schema.documents.workspaceId, input.workspaceId),
               eq(schema.documents.id, existing.id),
-              ...documentAccessConditions(input.access),
+              ...documentAccessConditions(input.workspaceId, input.access),
             ),
           )
           .returning();
@@ -938,7 +983,10 @@ export async function addDocumentToBase(
           sourceUpdatedAt: parseOptionalDate(input.sourceUpdatedAt),
           sourceVersion: cleanString(input.sourceVersion) ?? null,
           aclTags: cleanStringArray(input.aclTags),
-          visibility: input.visibility ?? "workspace",
+          authorityKind: authority.kind,
+          authorityWorkspaceId: authority.workspaceId,
+          authoritySubjectId: authority.subjectId,
+          visibility: authority.kind === "personal" ? "private" : "workspace",
           agentAccess: input.agentAccess ?? true,
           createdBy: input.createdBy ?? null,
           curationStatus: input.curationStatus ?? "none",
@@ -963,6 +1011,7 @@ export async function moveDocumentToBase(
     workspaceId: string;
     documentId: string;
     targetBaseId?: string | null | undefined;
+    organizationAuthorityGranted?: boolean | undefined;
     access?: DocumentAccessFilter | undefined;
   },
 ): Promise<Document> {
@@ -970,6 +1019,8 @@ export async function moveDocumentToBase(
     db,
     { accountId: input.accountId, workspaceId: input.workspaceId },
     async (scopedDb) => {
+      const viewerSubjectId = cleanString(input.access?.viewerSubjectId ?? null);
+      if (viewerSubjectId) await setSubjectRlsContext(scopedDb, viewerSubjectId);
       const [row] = await scopedDb
         .select()
         .from(schema.documents)
@@ -977,11 +1028,12 @@ export async function moveDocumentToBase(
           and(
             eq(schema.documents.workspaceId, input.workspaceId),
             eq(schema.documents.id, input.documentId),
-            ...documentAccessConditions(input.access),
+            ...documentAccessConditions(input.workspaceId, input.access),
           ),
         )
         .limit(1);
       if (!row) throw new Error(`Document not found: ${input.documentId}`);
+      assertOrganizationDocumentAuthority(row.authorityKind, input.organizationAuthorityGranted);
       const suggestion = (row.curation as { suggestedBaseId?: string | null } | null)
         ?.suggestedBaseId;
       const targetBaseId = input.targetBaseId ?? suggestion;
@@ -1020,7 +1072,7 @@ export async function moveDocumentToBase(
             and(
               eq(schema.documents.workspaceId, input.workspaceId),
               eq(schema.documents.id, input.documentId),
-              ...documentAccessConditions(input.access),
+              ...documentAccessConditions(input.workspaceId, input.access),
             ),
           )
           .returning();
@@ -1050,6 +1102,7 @@ export async function deleteDocumentFromBase(
     workspaceId: string;
     baseId: string;
     documentId: string;
+    organizationAuthorityGranted?: boolean | undefined;
     access?: DocumentAccessFilter | undefined;
   },
 ): Promise<void> {
@@ -1057,6 +1110,8 @@ export async function deleteDocumentFromBase(
     db,
     { accountId: input.accountId, workspaceId: input.workspaceId },
     async (scopedDb) => {
+      const viewerSubjectId = cleanString(input.access?.viewerSubjectId ?? null);
+      if (viewerSubjectId) await setSubjectRlsContext(scopedDb, viewerSubjectId);
       const [document] = await scopedDb
         .select()
         .from(schema.documents)
@@ -1064,13 +1119,17 @@ export async function deleteDocumentFromBase(
           and(
             eq(schema.documents.workspaceId, input.workspaceId),
             eq(schema.documents.id, input.documentId),
-            ...documentAccessConditions(input.access),
+            ...documentAccessConditions(input.workspaceId, input.access),
           ),
         )
         .limit(1);
       if (!document) {
         throw new Error(`Document not found: ${input.documentId}`);
       }
+      assertOrganizationDocumentAuthority(
+        document.authorityKind,
+        input.organizationAuthorityGranted,
+      );
       if (document.baseId !== input.baseId) {
         throw new Error(`Document not found: ${input.documentId}`);
       }
@@ -1080,7 +1139,7 @@ export async function deleteDocumentFromBase(
           and(
             eq(schema.documents.workspaceId, input.workspaceId),
             eq(schema.documents.id, input.documentId),
-            ...documentAccessConditions(input.access),
+            ...documentAccessConditions(input.workspaceId, input.access),
           ),
         );
     },
@@ -1093,7 +1152,7 @@ export async function listDocuments(
   baseId: string,
   access?: DocumentAccessFilter,
 ): Promise<Document[]> {
-  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+  return await withDocumentRls(db, workspaceId, access, async (scopedDb) => {
     const rows = await scopedDb
       .select()
       .from(schema.documents)
@@ -1101,7 +1160,7 @@ export async function listDocuments(
         and(
           eq(schema.documents.workspaceId, workspaceId),
           eq(schema.documents.baseId, baseId),
-          ...documentAccessConditions(access),
+          ...documentAccessConditions(workspaceId, access),
         ),
       )
       .orderBy(asc(schema.documents.createdAt));
@@ -1115,7 +1174,7 @@ export async function getDocument(
   documentId: string,
   access?: DocumentAccessFilter,
 ): Promise<Document | null> {
-  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+  return await withDocumentRls(db, workspaceId, access, async (scopedDb) => {
     const [row] = await scopedDb
       .select()
       .from(schema.documents)
@@ -1123,7 +1182,7 @@ export async function getDocument(
         and(
           eq(schema.documents.workspaceId, workspaceId),
           eq(schema.documents.id, documentId),
-          ...documentAccessConditions(access),
+          ...documentAccessConditions(workspaceId, access),
         ),
       )
       .limit(1);
@@ -1136,8 +1195,22 @@ export async function queueDocumentForReindex(
   workspaceId: string,
   documentId: string,
   access?: DocumentAccessFilter,
+  organizationAuthorityGranted?: boolean,
 ): Promise<Document> {
-  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+  return await withDocumentRls(db, workspaceId, access, async (scopedDb) => {
+    const [document] = await scopedDb
+      .select({ authorityKind: schema.documents.authorityKind })
+      .from(schema.documents)
+      .where(
+        and(
+          eq(schema.documents.workspaceId, workspaceId),
+          eq(schema.documents.id, documentId),
+          ...documentAccessConditions(workspaceId, access),
+        ),
+      )
+      .limit(1);
+    if (!document) throw new Error(`Document not found: ${documentId}`);
+    assertOrganizationDocumentAuthority(document.authorityKind, organizationAuthorityGranted);
     const [row] = await scopedDb
       .update(schema.documents)
       .set({
@@ -1149,7 +1222,7 @@ export async function queueDocumentForReindex(
         and(
           eq(schema.documents.workspaceId, workspaceId),
           eq(schema.documents.id, documentId),
-          ...documentAccessConditions(access),
+          ...documentAccessConditions(workspaceId, access),
         ),
       )
       .returning();
@@ -1158,6 +1231,15 @@ export async function queueDocumentForReindex(
   });
 }
 
+function assertOrganizationDocumentAuthority(
+  authorityKind: string,
+  organizationAuthorityGranted: boolean | undefined,
+): void {
+  if (authorityKind === "organization" && organizationAuthorityGranted !== true) {
+    throw new Error("organization document mutations require exact account authority");
+  }
+}
+
 export async function indexDocumentNow(
   db: Database,
   objectStorage: ObjectStorage,
@@ -1165,10 +1247,12 @@ export async function indexDocumentNow(
   documentId: string,
   services: DocumentServices = createDocumentServices(),
   hooks: DocumentIndexHooks = {},
+  access?: DocumentAccessFilter,
 ): Promise<Document> {
-  const [loadedDocument] = await withWorkspaceRls(
+  const [loadedDocument] = await withDocumentRls(
     db,
     workspaceId,
+    access,
     async (scopedDb) =>
       await scopedDb
         .select()
@@ -1181,7 +1265,7 @@ export async function indexDocumentNow(
   if (!loadedDocument) throw new Error(`Document not found: ${documentId}`);
   let document: DocumentRow = loadedDocument;
   const file = await requireReadyFile(db, workspaceId, document.fileId);
-  await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+  await withDocumentRls(db, workspaceId, access, async (scopedDb) => {
     await scopedDb
       .update(schema.documents)
       .set({
@@ -1217,9 +1301,10 @@ export async function indexDocumentNow(
         `Embedding provider returned ${embeddings.length} embeddings for ${chunks.length} chunks`,
       );
     }
-    await withWorkspaceRls(
+    await withDocumentRls(
       db,
       workspaceId,
+      access,
       async (scopedDb) =>
         await scopedDb.transaction(async (tx) => {
           await tx
@@ -1238,6 +1323,9 @@ export async function indexDocumentNow(
                 documentId,
                 baseId: document.baseId,
                 fileId: file.id,
+                authorityKind: document.authorityKind,
+                authorityWorkspaceId: document.authorityWorkspaceId,
+                authoritySubjectId: document.authoritySubjectId,
                 chunkIndex: index,
                 text: chunk.text,
                 metadata: {
@@ -1280,9 +1368,10 @@ export async function indexDocumentNow(
         }),
     );
   } catch (error) {
-    const [failed] = await withWorkspaceRls(
+    const [failed] = await withDocumentRls(
       db,
       workspaceId,
+      access,
       async (scopedDb) =>
         await scopedDb
           .update(schema.documents)
@@ -1303,7 +1392,7 @@ export async function indexDocumentNow(
   // that created/queued it. Public reads remain fail-closed when no subject is
   // supplied; the creator subject is the document's frozen access principal.
   const updated = await getDocument(db, workspaceId, documentId, {
-    viewerSubjectId: document.createdBy,
+    viewerSubjectId: document.authoritySubjectId,
   });
   if (!updated) throw new Error(`Document disappeared after indexing: ${documentId}`);
   return updated;
@@ -1322,9 +1411,10 @@ async function curateDroppedDocument(
   // it with heuristics: indexing still proceeds, but the drop remains an
   // ordinary uncured document with its caller-supplied title and metadata.
   if (!services.curator) {
-    const [updated] = await withWorkspaceRls(
+    const [updated] = await withDocumentRls(
       db,
       document.workspaceId,
+      { viewerSubjectId: document.authoritySubjectId },
       async (scopedDb) =>
         await scopedDb
           .update(schema.documents)
@@ -1380,9 +1470,10 @@ async function curateDroppedDocument(
   ) {
     // The (workspace, base, file) unique index means a same-file twin already
     // in the target base blocks the move; keep it as a suggestion instead.
-    const conflict = await withWorkspaceRls(
+    const conflict = await withDocumentRls(
       db,
       document.workspaceId,
+      { viewerSubjectId: document.authoritySubjectId },
       async (scopedDb) =>
         await scopedDb
           .select({ id: schema.documents.id })
@@ -1413,9 +1504,10 @@ async function curateDroppedDocument(
     : moveToBaseId
       ? "auto_filed"
       : "suggested";
-  const [updated] = await withWorkspaceRls(
+  const [updated] = await withDocumentRls(
     db,
     document.workspaceId,
+    { viewerSubjectId: document.authoritySubjectId },
     async (scopedDb) =>
       await scopedDb
         .update(schema.documents)
@@ -1445,6 +1537,7 @@ export async function searchDocuments(
   input: DocumentSearchInput,
   services: Pick<DocumentServices, "embedder"> = createDocumentServices(),
 ): Promise<DocumentSearchResult[]> {
+  await assertDocumentAccountWorkspace(db, input.accountId, input.workspaceId);
   const mode = input.mode ?? "hybrid";
   const limit = Math.min(Math.max(input.limit ?? 5, 1), 50);
   const candidateLimit = mode === "hybrid" ? Math.min(limit * 4, 100) : limit;
@@ -1471,6 +1564,42 @@ export async function searchDocuments(
   return mergeDocumentSearchRows(rows, mode).slice(0, limit);
 }
 
+/**
+ * Canonical effective retrieval composition for API, SDK, and MCP surfaces.
+ * Callers supply the already-authorized immutable initiating subject; no
+ * request/tool input can replace it with another user's personal authority.
+ */
+export async function searchEffectiveDocuments(
+  db: Database,
+  input: EffectiveDocumentSearchInput,
+  services: Pick<DocumentServices, "embedder"> = createDocumentServices(),
+): Promise<DocumentSearchResult[]> {
+  const initiatingSubjectId = cleanString(input.initiatingSubjectId);
+  if (!initiatingSubjectId) {
+    throw new Error("effective document retrieval requires an initiating subject");
+  }
+  return await searchDocuments(
+    db,
+    {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      query: input.query,
+      baseIds: input.baseIds,
+      limit: input.limit,
+      mode: input.mode,
+      sourceKinds: input.sourceKinds,
+      aclTags: input.aclTags,
+      // Construct the lower-level access filter here instead of spreading the
+      // caller input, so an untyped/legacy access override is always ignored.
+      access: {
+        viewerSubjectId: initiatingSubjectId,
+        ...(input.surface === "agent" ? { agentOnly: true } : {}),
+      },
+    },
+    services,
+  );
+}
+
 async function vectorSearchDocuments(
   db: Database,
   input: DocumentSearchInput,
@@ -1480,13 +1609,16 @@ async function vectorSearchDocuments(
   const queryEmbedding = await services.embedder.embedQuery(input.query);
   validateEmbedding(queryEmbedding, services.embedder.dimensions, services.embedder.model);
   const distance = sql<number>`${schema.documentChunks.embedding} <=> ${vectorLiteral(queryEmbedding)}::vector`;
-  const rows = await withWorkspaceRls(
+  const rows = await withDocumentAccountRls(
     db,
+    input.accountId,
     input.workspaceId,
+    input.access,
     async (scopedDb) =>
       await scopedDb
         .select({
           chunkId: schema.documentChunks.id,
+          workspaceId: schema.documentChunks.workspaceId,
           documentId: schema.documentChunks.documentId,
           baseId: schema.documentChunks.baseId,
           fileId: schema.documentChunks.fileId,
@@ -1503,6 +1635,9 @@ async function vectorSearchDocuments(
           sourceUpdatedAt: schema.documents.sourceUpdatedAt,
           sourceVersion: schema.documents.sourceVersion,
           aclTags: schema.documents.aclTags,
+          authorityKind: schema.documents.authorityKind,
+          authorityWorkspaceId: schema.documents.authorityWorkspaceId,
+          authoritySubjectId: schema.documents.authoritySubjectId,
           distance,
         })
         .from(schema.documentChunks)
@@ -1512,7 +1647,7 @@ async function vectorSearchDocuments(
         .limit(limit),
   );
   return rows.map((row) => ({
-    ...mapSearchRowBase(row, input.workspaceId),
+    ...mapSearchRowBase(row),
     vectorScore: 1 / (1 + Number(row.distance)),
     keywordScore: null,
   }));
@@ -1524,13 +1659,16 @@ async function keywordSearchDocuments(
   limit: number,
 ): Promise<CombinedSearchRow[]> {
   const rank = sql<number>`ts_rank_cd(to_tsvector('simple', ${schema.documentChunks.text}), plainto_tsquery('simple', ${input.query}))`;
-  const rows = await withWorkspaceRls(
+  const rows = await withDocumentAccountRls(
     db,
+    input.accountId,
     input.workspaceId,
+    input.access,
     async (scopedDb) =>
       await scopedDb
         .select({
           chunkId: schema.documentChunks.id,
+          workspaceId: schema.documentChunks.workspaceId,
           documentId: schema.documentChunks.documentId,
           baseId: schema.documentChunks.baseId,
           fileId: schema.documentChunks.fileId,
@@ -1547,6 +1685,9 @@ async function keywordSearchDocuments(
           sourceUpdatedAt: schema.documents.sourceUpdatedAt,
           sourceVersion: schema.documents.sourceVersion,
           aclTags: schema.documents.aclTags,
+          authorityKind: schema.documents.authorityKind,
+          authorityWorkspaceId: schema.documents.authorityWorkspaceId,
+          authoritySubjectId: schema.documents.authoritySubjectId,
           rank,
         })
         .from(schema.documentChunks)
@@ -1561,7 +1702,7 @@ async function keywordSearchDocuments(
         .limit(limit),
   );
   return rows.map((row) => ({
-    ...mapSearchRowBase(row, input.workspaceId),
+    ...mapSearchRowBase(row),
     vectorScore: null,
     keywordScore: normalizeKeywordScore(Number(row.rank)),
   }));
@@ -1569,17 +1710,21 @@ async function keywordSearchDocuments(
 
 export async function getDocumentChunk(
   db: Database,
+  accountId: string,
   workspaceId: string,
   chunkId: string,
   access?: DocumentAccessFilter,
 ): Promise<DocumentSearchResult | null> {
-  const [row] = await withWorkspaceRls(
+  const [row] = await withDocumentAccountRls(
     db,
+    accountId,
     workspaceId,
+    access,
     async (scopedDb) =>
       await scopedDb
         .select({
           chunkId: schema.documentChunks.id,
+          workspaceId: schema.documentChunks.workspaceId,
           documentId: schema.documentChunks.documentId,
           baseId: schema.documentChunks.baseId,
           fileId: schema.documentChunks.fileId,
@@ -1596,22 +1741,26 @@ export async function getDocumentChunk(
           sourceUpdatedAt: schema.documents.sourceUpdatedAt,
           sourceVersion: schema.documents.sourceVersion,
           aclTags: schema.documents.aclTags,
+          authorityKind: schema.documents.authorityKind,
+          authorityWorkspaceId: schema.documents.authorityWorkspaceId,
+          authoritySubjectId: schema.documents.authoritySubjectId,
         })
         .from(schema.documentChunks)
         .innerJoin(schema.documents, eq(schema.documentChunks.documentId, schema.documents.id))
         .where(
           and(
-            eq(schema.documentChunks.workspaceId, workspaceId),
+            eq(schema.documents.accountId, accountId),
+            eq(schema.documentChunks.accountId, accountId),
             eq(schema.documentChunks.id, chunkId),
             eq(schema.documents.status, "ready"),
-            ...documentAccessConditions(access),
+            ...documentAccessConditions(workspaceId, access),
           ),
         )
         .limit(1),
   );
   if (!row) return null;
   return {
-    ...mapSearchRowBase(row, workspaceId),
+    ...mapSearchRowBase(row),
     score: 1,
     matchType: "hybrid",
     vectorScore: null,
@@ -1628,65 +1777,139 @@ type CombinedSearchRow = SearchRowBase & {
   keywordScore: number | null;
 };
 
+export function resolveDocumentAuthority(input: {
+  kind?: DocumentAuthorityKind | undefined;
+  legacyVisibility?: DocumentVisibility | undefined;
+  workspaceId: string;
+  initiatingSubjectId?: string | null | undefined;
+}): DocumentAuthority {
+  const legacyKind = input.legacyVisibility === "private" ? "personal" : "workspace";
+  const kind = input.kind ?? legacyKind;
+  if (
+    input.kind &&
+    input.legacyVisibility &&
+    (input.legacyVisibility === "private") !== (input.kind === "personal")
+  ) {
+    throw new Error("document authorityKind conflicts with legacy visibility");
+  }
+  if (kind === "organization") {
+    return { kind, workspaceId: null, subjectId: null };
+  }
+  if (kind === "workspace") {
+    return { kind, workspaceId: input.workspaceId, subjectId: null };
+  }
+  const subjectId = cleanString(input.initiatingSubjectId ?? null);
+  if (!subjectId) throw new Error("personal documents require an initiating subject");
+  if (new TextEncoder().encode(subjectId).byteLength > DOCUMENT_AUTHORITY_SUBJECT_MAX_BYTES) {
+    throw new Error(
+      `personal document initiating subject exceeds ${DOCUMENT_AUTHORITY_SUBJECT_MAX_BYTES} UTF-8 bytes`,
+    );
+  }
+  return { kind, workspaceId: input.workspaceId, subjectId };
+}
+
+async function withDocumentRls<T>(
+  db: Database,
+  workspaceId: string,
+  access: DocumentAccessFilter | undefined,
+  fn: (db: Database) => Promise<T>,
+): Promise<T> {
+  const subjectId = cleanString(access?.viewerSubjectId ?? null);
+  return subjectId
+    ? await withWorkspaceSubjectRls(db, workspaceId, subjectId, fn)
+    : await withWorkspaceRls(db, workspaceId, fn);
+}
+
+async function withDocumentAccountRls<T>(
+  db: Database,
+  accountId: string,
+  workspaceId: string,
+  access: DocumentAccessFilter | undefined,
+  fn: (db: Database) => Promise<T>,
+): Promise<T> {
+  const context = await assertDocumentAccountWorkspace(db, accountId, workspaceId);
+  const subjectId = cleanString(access?.viewerSubjectId ?? null);
+  return await withRlsContext(db, context, async (scopedDb) => {
+    if (subjectId) await setSubjectRlsContext(scopedDb, subjectId);
+    return await fn(scopedDb);
+  });
+}
+
+async function assertDocumentAccountWorkspace(
+  db: Database,
+  accountId: string,
+  workspaceId: string,
+) {
+  const context = await rlsContextForWorkspace(db, workspaceId);
+  if (context.accountId !== accountId) {
+    throw new Error("document account/workspace authority mismatch");
+  }
+  return context;
+}
+
 /**
  * Visibility/agent scoping shared by every document read path. Fail-closed:
  * with no filter supplied, private documents are invisible.
  */
-function documentAccessConditions(access: DocumentAccessFilter | undefined): SQL[] {
+function documentAccessConditions(
+  workspaceId: string,
+  access: DocumentAccessFilter | undefined,
+): SQL[] {
+  const organization = eq(schema.documents.authorityKind, "organization");
+  const workspace = and(
+    eq(schema.documents.authorityKind, "workspace"),
+    eq(schema.documents.authorityWorkspaceId, workspaceId),
+  );
+  const viewer = cleanString(access?.viewerSubjectId ?? null);
+  const personal = viewer
+    ? and(
+        eq(schema.documents.authorityKind, "personal"),
+        eq(schema.documents.authorityWorkspaceId, workspaceId),
+        eq(schema.documents.authoritySubjectId, viewer),
+      )
+    : undefined;
+  const authority = viewer
+    ? (or(organization, workspace, personal) ?? organization)
+    : (or(organization, workspace) ?? organization);
   if (access?.agentOnly) {
-    const viewer = access.viewerSubjectId;
-    const visibility = viewer
-      ? or(eq(schema.documents.visibility, "workspace"), eq(schema.documents.createdBy, viewer))
-      : eq(schema.documents.visibility, "workspace");
-    return [eq(schema.documents.agentAccess, true), ...(visibility ? [visibility] : [])];
+    return [eq(schema.documents.agentAccess, true), authority];
   }
-  const viewer = access?.viewerSubjectId;
-  if (viewer) {
-    const condition = or(
-      eq(schema.documents.visibility, "workspace"),
-      eq(schema.documents.createdBy, viewer),
-    );
-    return condition ? [condition] : [];
-  }
-  return [eq(schema.documents.visibility, "workspace")];
+  return [authority];
 }
 
 function documentMatchesAccess(
-  document: Pick<DocumentAccessRecord, "visibility" | "createdBy" | "agentAccess">,
+  document: Pick<DocumentAccessRecord, "authorityKind" | "authoritySubjectId" | "agentAccess">,
   access: DocumentAccessFilter | undefined,
 ): boolean {
   if (access?.agentOnly) {
-    return (
-      document.agentAccess &&
-      (document.visibility !== "private" ||
-        (!!access.viewerSubjectId && document.createdBy === access.viewerSubjectId))
-    );
+    return document.agentAccess && canViewDocument(document, access.viewerSubjectId);
   }
   return canViewDocument(document, access?.viewerSubjectId);
 }
 
 /** Whether a single already-fetched document is readable by this human viewer. */
 export function canViewDocument(
-  document: Pick<DocumentAccessRecord, "visibility" | "createdBy">,
+  document: Pick<DocumentAccessRecord, "authorityKind" | "authoritySubjectId">,
   viewerSubjectId: string | null | undefined,
 ): boolean {
   return (
-    document.visibility !== "private" ||
-    (!!viewerSubjectId && document.createdBy === viewerSubjectId)
+    document.authorityKind !== "personal" ||
+    (!!viewerSubjectId && document.authoritySubjectId === viewerSubjectId)
   );
 }
 
 type DocumentAccessRecord = {
-  visibility: string;
-  createdBy: string | null;
+  authorityKind: string;
+  authoritySubjectId: string | null;
   agentAccess: boolean;
 };
 
 function documentSearchConditions(input: DocumentSearchInput, embeddingModel?: string): SQL[] {
   const conditions: SQL[] = [
     eq(schema.documents.status, "ready"),
-    eq(schema.documentChunks.workspaceId, input.workspaceId),
-    ...documentAccessConditions(input.access),
+    eq(schema.documents.accountId, input.accountId),
+    eq(schema.documentChunks.accountId, input.accountId),
+    ...documentAccessConditions(input.workspaceId, input.access),
   ];
   if (embeddingModel) {
     conditions.push(eq(schema.documentChunks.embeddingModel, embeddingModel));
@@ -1704,31 +1927,32 @@ function documentSearchConditions(input: DocumentSearchInput, embeddingModel?: s
   return conditions;
 }
 
-function mapSearchRowBase(
-  row: {
-    chunkId: string;
-    documentId: string;
-    baseId: string;
-    fileId: string;
-    title: string;
-    text: string;
-    chunkIndex: number;
-    metadata: Record<string, unknown>;
-    sourceKind: string;
-    sourceUri: string | null;
-    sourceExternalId: string | null;
-    sourceTitle: string | null;
-    sourceAuthor: string | null;
-    sourceCreatedAt: Date | null;
-    sourceUpdatedAt: Date | null;
-    sourceVersion: string | null;
-    aclTags: string[];
-  },
-  workspaceId: string,
-): SearchRowBase {
+function mapSearchRowBase(row: {
+  chunkId: string;
+  workspaceId: string;
+  documentId: string;
+  baseId: string;
+  fileId: string;
+  title: string;
+  text: string;
+  chunkIndex: number;
+  metadata: Record<string, unknown>;
+  sourceKind: string;
+  sourceUri: string | null;
+  sourceExternalId: string | null;
+  sourceTitle: string | null;
+  sourceAuthor: string | null;
+  sourceCreatedAt: Date | null;
+  sourceUpdatedAt: Date | null;
+  sourceVersion: string | null;
+  aclTags: string[];
+  authorityKind: string;
+  authorityWorkspaceId: string | null;
+  authoritySubjectId: string | null;
+}): SearchRowBase {
   return {
     chunkId: row.chunkId,
-    workspaceId,
+    workspaceId: row.workspaceId,
     documentId: row.documentId,
     baseId: row.baseId,
     fileId: row.fileId,
@@ -1745,6 +1969,9 @@ function mapSearchRowBase(
     sourceUpdatedAt: row.sourceUpdatedAt?.toISOString() ?? null,
     sourceVersion: row.sourceVersion,
     aclTags: cleanStringArray(row.aclTags),
+    authorityKind: normalizeDocumentAuthorityKind(row.authorityKind),
+    authorityWorkspaceId: row.authorityWorkspaceId,
+    authoritySubjectId: row.authoritySubjectId,
   };
 }
 
@@ -2029,6 +2256,9 @@ function mapDocument(row: typeof schema.documents.$inferSelect): Document {
     sourceUpdatedAt: row.sourceUpdatedAt?.toISOString() ?? null,
     sourceVersion: row.sourceVersion,
     aclTags: cleanStringArray(row.aclTags),
+    authorityKind: normalizeDocumentAuthorityKind(row.authorityKind),
+    authorityWorkspaceId: row.authorityWorkspaceId,
+    authoritySubjectId: row.authoritySubjectId,
     visibility: normalizeDocumentVisibility(row.visibility),
     createdBy: row.createdBy,
     agentAccess: row.agentAccess,
@@ -2041,6 +2271,16 @@ function mapDocument(row: typeof schema.documents.$inferSelect): Document {
   };
 }
 
+function normalizeDocumentAuthorityKind(value: string): DocumentAuthorityKind {
+  switch (value) {
+    case "organization":
+    case "personal":
+      return value;
+    default:
+      return "workspace";
+  }
+}
+
 function normalizeDocumentVisibility(value: string): DocumentVisibility {
   return value === "private" ? "private" : "workspace";
 }