@opengeni/documents 0.5.39 → 0.6.9-canary.0

package/dist/index.js

@@ -1,6 +1,14 @@
 // src/index.ts
 import {
-  requireFile,
+  KnowledgeProviderCitation,
+  DocumentAuthorityReclassification,
+  ListDocumentAuthorityReclassificationsResponse,
+  DocumentDefaultCollectionBackfill
+} from "@opengeni/contracts";
+import {
+  createPersonalDocumentAuthority,
+  getFilesForSubject,
+  resolveDocumentOriginalFileForSubject,
   rlsContextForWorkspace,
   setSubjectRlsContext,
   withRlsContext,
@@ -8,9 +16,20 @@ import {
   withWorkspaceSubjectRls
 } from "@opengeni/db";
 import * as schema from "@opengeni/db/schema";
-import { createHash } from "crypto";
-import { and, asc, desc, eq, gt, inArray, isNotNull, or, sql } from "drizzle-orm";
-import { KNOWLEDGE_BROWSE_CURSOR_MAX_CHARS } from "@opengeni/contracts";
+import { retryWhileMissing } from "@opengeni/storage";
+import { createHash, randomUUID } from "crypto";
+import { and, asc, desc, eq, gt, inArray, isNotNull, isNull, or, sql } from "drizzle-orm";
+import {
+  KNOWLEDGE_BROWSE_CURSOR_MAX_CHARS,
+  KNOWLEDGE_BROWSE_MAX_LIMIT,
+  KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES,
+  KNOWLEDGE_SEARCH_MAX_RESPONSE_BYTES,
+  KNOWLEDGE_SEARCH_MAX_FLOOR_OMISSIONS,
+  KNOWLEDGE_SEARCH_MAX_RESULTS,
+  KNOWLEDGE_SEARCH_MIN_KEYWORD_SCORE,
+  KNOWLEDGE_SEARCH_MIN_VECTOR_SCORE,
+  KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN
+} from "@opengeni/contracts";
 
 // src/knowledge-projection.ts
 import {
@@ -694,6 +713,135 @@ async function listDocumentBasesEnsuringDefault(db, input) {
   await ensureDefaultBase(db, input);
   return await listDocumentBases(db, input.workspaceId);
 }
+async function runDocumentDefaultCollectionBackfill(db, input) {
+  return await withDocumentAccountRls(
+    db,
+    input.accountId,
+    input.workspaceId,
+    { viewerSubjectId: input.actorSubjectId },
+    async (scopedDb) => {
+      const command = {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        actorSubjectId: input.actorSubjectId,
+        runId: input.runId,
+        operationId: input.operationId,
+        batchSize: input.batchSize,
+        accountAdminAuthorization: input.accountAdminAuthorization
+      };
+      const rows = await scopedDb.execute(sql`
+        SELECT run_document_default_collection_backfill(
+          ${JSON.stringify(command)}::jsonb
+        ) AS result
+      `);
+      const row = rows[0];
+      if (!row) throw new Error("Document Default collection backfill returned no result");
+      return DocumentDefaultCollectionBackfill.parse(row.result);
+    }
+  );
+}
+async function reclassifyDocumentAuthority(db, input) {
+  return await withDocumentAccountRls(
+    db,
+    input.accountId,
+    input.workspaceId,
+    { viewerSubjectId: input.actorSubjectId },
+    async (scopedDb) => {
+      const command = {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        documentId: input.documentId,
+        operationId: input.operationId,
+        actorSubjectId: input.actorSubjectId,
+        expectedAuthority: input.expectedAuthority,
+        targetAuthorityKind: input.targetAuthorityKind,
+        accountAdminAuthorization: input.accountAdminAuthorization
+      };
+      const rows = await scopedDb.execute(sql`
+        SELECT reclassify_document_authority(${JSON.stringify(command)}::jsonb) AS result
+      `);
+      const row = rows[0];
+      if (!row) throw new Error("Document authority reclassification returned no result");
+      return DocumentAuthorityReclassification.parse(row.result);
+    }
+  );
+}
+async function listDocumentAuthorityReclassifications(db, input) {
+  const limit = input.limit ?? 50;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+    throw new Error("document authority receipt limit must be between 1 and 100");
+  }
+  const cursor = input.cursor ? decodeDocumentAuthorityReclassificationCursor(input.cursor, input) : null;
+  return await withDocumentAccountRls(
+    db,
+    input.accountId,
+    input.workspaceId,
+    { viewerSubjectId: input.actorSubjectId },
+    async (scopedDb) => {
+      const rows = await scopedDb.execute(sql`
+        SELECT list_document_authority_reclassifications(
+          ${input.accountId}::uuid,
+          ${input.workspaceId}::uuid,
+          ${input.actorSubjectId},
+          ${input.documentId}::uuid,
+          ${limit + 1}::integer,
+          ${cursor?.createdAt ?? null}::timestamptz,
+          ${cursor?.operationId ?? null}::uuid
+        ) AS result
+      `);
+      const parsed = rows.map((row) => DocumentAuthorityReclassification.parse(row.result));
+      const hasMore = parsed.length > limit;
+      const receipts = parsed.slice(0, limit);
+      const tail = hasMore ? receipts.at(-1) : null;
+      return ListDocumentAuthorityReclassificationsResponse.parse({
+        receipts,
+        hasMore,
+        nextCursor: tail ? encodeDocumentAuthorityReclassificationCursor(input, {
+          createdAt: tail.createdAt,
+          operationId: tail.operationId
+        }) : null
+      });
+    }
+  );
+}
+function documentAuthorityReclassificationCursorScope(input) {
+  return createHash("sha256").update(
+    JSON.stringify([
+      "document_authority_reclassification_cursor",
+      1,
+      input.accountId,
+      input.workspaceId,
+      input.documentId,
+      input.actorSubjectId
+    ]),
+    "utf8"
+  ).digest("hex").slice(0, 32);
+}
+function encodeDocumentAuthorityReclassificationCursor(scope, cursor) {
+  return Buffer.from(
+    JSON.stringify({
+      v: 1,
+      s: documentAuthorityReclassificationCursorScope(scope),
+      t: cursor.createdAt,
+      i: cursor.operationId
+    }),
+    "utf8"
+  ).toString("base64url");
+}
+function decodeDocumentAuthorityReclassificationCursor(value, scope) {
+  try {
+    if (!value || value.length > 1024) throw new Error("cursor length");
+    const bytes = Buffer.from(value, "base64url");
+    if (bytes.toString("base64url") !== value) throw new Error("cursor encoding");
+    const parsed = JSON.parse(bytes.toString("utf8"));
+    if (Object.keys(parsed).sort().join(",") !== "i,s,t,v" || parsed.v !== 1 || parsed.s !== documentAuthorityReclassificationCursorScope(scope) || typeof parsed.t !== "string" || !Number.isFinite(new Date(parsed.t).getTime()) || typeof parsed.i !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(parsed.i)) {
+      throw new Error("cursor payload");
+    }
+    return { createdAt: parsed.t, operationId: parsed.i };
+  } catch (error) {
+    throw new Error("invalid document authority receipt cursor", { cause: error });
+  }
+}
 async function addDocumentToBase(db, input) {
   return await withRlsContext(
     db,
@@ -715,7 +863,18 @@ async function addDocumentToBase(db, input) {
       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);
+      const initiatingSubjectId = cleanString(input.initiatingSubjectId ?? null);
+      const createdBy = cleanString(input.createdBy ?? null);
+      if (initiatingSubjectId && createdBy && initiatingSubjectId !== createdBy) {
+        throw new Error("document file authority must match the exact initiating subject");
+      }
+      const fileAuthoritySubjectId = initiatingSubjectId ?? createdBy ?? null;
+      const file = await requireReadyFile(scopedDb, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        subjectId: fileAuthoritySubjectId,
+        fileId: input.fileId
+      });
       const knowledgeSourceIdentity = cleanString(input.knowledgeSourceIdentity ?? null);
       if (knowledgeSourceIdentity && knowledgeSourceIdentity.length > 512) {
         throw new Error("knowledge source document identity exceeds 512 characters");
@@ -762,33 +921,47 @@ async function addDocumentToBase(db, input) {
         ).returning();
         return mapDocument(updated ?? existing);
       }
-      const [row] = await scopedDb.insert(schema.documents).values({
-        accountId: input.accountId,
-        workspaceId: input.workspaceId,
-        baseId: input.baseId,
-        fileId: input.fileId,
-        status: "queued",
-        title: cleanString(input.title) ?? cleanString(input.sourceTitle) ?? file.filename,
-        parser: DEFAULT_DOCUMENT_PARSER,
-        sourceKind: input.sourceKind ?? "manual_upload",
-        sourceUri: cleanString(input.sourceUri) ?? null,
-        sourceExternalId: cleanString(input.sourceExternalId) ?? null,
-        sourceTitle: cleanString(input.sourceTitle) ?? null,
-        sourceAuthor: cleanString(input.sourceAuthor) ?? null,
-        sourceCreatedAt: parseOptionalDate(input.sourceCreatedAt),
-        sourceUpdatedAt: parseOptionalDate(input.sourceUpdatedAt),
-        sourceVersion: cleanString(input.sourceVersion) ?? null,
-        knowledgeSourceIdentity,
-        aclTags: cleanStringArray(input.aclTags),
-        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",
-        updatedAt: now
-      }).returning();
+      const documentId = randomUUID();
+      const row = await scopedDb.transaction(async (tx) => {
+        const userAuthority = authority.kind === "personal" ? await createPersonalDocumentAuthority(tx, {
+          accountId: input.accountId,
+          workspaceId: input.workspaceId,
+          subjectId: authority.subjectId,
+          documentId
+        }) : null;
+        const [inserted] = await tx.insert(schema.documents).values({
+          id: documentId,
+          accountId: input.accountId,
+          workspaceId: input.workspaceId,
+          baseId: input.baseId,
+          fileId: input.fileId,
+          status: "queued",
+          title: cleanString(input.title) ?? cleanString(input.sourceTitle) ?? file.filename,
+          parser: DEFAULT_DOCUMENT_PARSER,
+          sourceKind: input.sourceKind ?? "manual_upload",
+          sourceUri: cleanString(input.sourceUri) ?? null,
+          sourceExternalId: cleanString(input.sourceExternalId) ?? null,
+          sourceTitle: cleanString(input.sourceTitle) ?? null,
+          sourceAuthor: cleanString(input.sourceAuthor) ?? null,
+          sourceCreatedAt: parseOptionalDate(input.sourceCreatedAt),
+          sourceUpdatedAt: parseOptionalDate(input.sourceUpdatedAt),
+          sourceVersion: cleanString(input.sourceVersion) ?? null,
+          knowledgeSourceIdentity,
+          aclTags: cleanStringArray(input.aclTags),
+          authorityKind: authority.kind,
+          authorityWorkspaceId: userAuthority ? null : authority.workspaceId,
+          authoritySubjectId: authority.subjectId,
+          authorityId: userAuthority?.authorityId ?? null,
+          ownerOrganizationMembershipId: userAuthority?.ownerOrganizationMembershipId ?? null,
+          originWorkspaceId: input.workspaceId,
+          visibility: authority.kind === "personal" ? "private" : "workspace",
+          agentAccess: input.agentAccess ?? true,
+          createdBy: fileAuthoritySubjectId,
+          curationStatus: input.curationStatus ?? "none",
+          updatedAt: now
+        }).returning();
+        return inserted;
+      });
       if (!row) throw new Error("Failed to create document");
       return mapDocument(row);
     }
@@ -803,7 +976,7 @@ async function moveDocumentToBase(db, input) {
       if (viewerSubjectId) await setSubjectRlsContext(scopedDb, viewerSubjectId);
       const [row] = await scopedDb.select().from(schema.documents).where(
         and(
-          eq(schema.documents.workspaceId, input.workspaceId),
+          eq(schema.documents.accountId, input.accountId),
           eq(schema.documents.id, input.documentId),
           ...documentAccessConditions(input.workspaceId, input.access)
         )
@@ -816,11 +989,11 @@ async function moveDocumentToBase(db, input) {
         throw new Error("document has no suggested base; pass targetBaseId");
       }
       if (targetBaseId === row.baseId) return mapDocument(row);
-      const base = await getDocumentBase(scopedDb, input.workspaceId, targetBaseId);
+      const base = await getDocumentBase(scopedDb, row.workspaceId, targetBaseId);
       if (!base) throw new Error(`Document base not found: ${targetBaseId}`);
       const [conflict] = await scopedDb.select({ id: schema.documents.id }).from(schema.documents).where(
         and(
-          eq(schema.documents.workspaceId, input.workspaceId),
+          eq(schema.documents.workspaceId, row.workspaceId),
           eq(schema.documents.baseId, targetBaseId),
           ...row.knowledgeSourceIdentity ? [eq(schema.documents.knowledgeSourceIdentity, row.knowledgeSourceIdentity)] : [eq(schema.documents.fileId, row.fileId)]
         )
@@ -836,7 +1009,7 @@ async function moveDocumentToBase(db, input) {
           updatedAt: now
         }).where(
           and(
-            eq(schema.documents.workspaceId, input.workspaceId),
+            eq(schema.documents.workspaceId, row.workspaceId),
             eq(schema.documents.id, input.documentId),
             ...documentAccessConditions(input.workspaceId, input.access)
           )
@@ -844,7 +1017,7 @@ async function moveDocumentToBase(db, input) {
         if (updated) {
           await tx.update(schema.documentChunks).set({ baseId: targetBaseId }).where(
             and(
-              eq(schema.documentChunks.workspaceId, input.workspaceId),
+              eq(schema.documentChunks.workspaceId, row.workspaceId),
               eq(schema.documentChunks.documentId, input.documentId)
             )
           );
@@ -865,7 +1038,7 @@ async function deleteDocumentFromBase(db, input) {
       if (viewerSubjectId) await setSubjectRlsContext(scopedDb, viewerSubjectId);
       const [document] = await scopedDb.select().from(schema.documents).where(
         and(
-          eq(schema.documents.workspaceId, input.workspaceId),
+          eq(schema.documents.accountId, input.accountId),
           eq(schema.documents.id, input.documentId),
           ...documentAccessConditions(input.workspaceId, input.access)
         )
@@ -882,7 +1055,7 @@ async function deleteDocumentFromBase(db, input) {
       }
       await scopedDb.delete(schema.documents).where(
         and(
-          eq(schema.documents.workspaceId, input.workspaceId),
+          eq(schema.documents.accountId, input.accountId),
           eq(schema.documents.id, input.documentId),
           ...documentAccessConditions(input.workspaceId, input.access)
         )
@@ -902,6 +1075,12 @@ async function listDocuments(db, workspaceId, baseId, access) {
     return rows.map(mapDocument);
   });
 }
+async function listAccessibleDocuments(db, workspaceId, access) {
+  return await withDocumentRls(db, workspaceId, access, async (scopedDb) => {
+    const rows = await scopedDb.select().from(schema.documents).where(and(...documentAccessConditions(workspaceId, access))).orderBy(desc(schema.documents.updatedAt), asc(schema.documents.createdAt));
+    return rows.map(mapDocument);
+  });
+}
 async function listEffectiveIndexedDocuments(db, input) {
   const initiatingSubjectId = canonicalEffectiveDocumentSubject(input.initiatingSubjectId);
   const limit = input.limit ?? 50;
@@ -913,10 +1092,13 @@ async function listEffectiveIndexedDocuments(db, input) {
     workspaceId: input.workspaceId,
     initiatingSubjectId
   }) : 0n;
-  const access = {
-    agentOnly: true,
-    viewerSubjectId: initiatingSubjectId
-  };
+  const access = await resolveEffectiveDocumentAccess(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    initiatingSubjectId,
+    surface: "agent",
+    agentAuthority: input.agentAuthority
+  });
   const rows = await withDocumentAccountRls(
     db,
     input.accountId,
@@ -1000,23 +1182,33 @@ function canonicalEffectiveDocumentSubject(value) {
 async function getDocument(db, workspaceId, documentId, access) {
   return await withDocumentRls(db, workspaceId, access, async (scopedDb) => {
     const [row] = await scopedDb.select().from(schema.documents).where(
-      and(
-        eq(schema.documents.workspaceId, workspaceId),
-        eq(schema.documents.id, documentId),
-        ...documentAccessConditions(workspaceId, access)
-      )
+      and(eq(schema.documents.id, documentId), ...documentAccessConditions(workspaceId, access))
+    ).limit(1);
+    return row ? mapDocument(row) : null;
+  });
+}
+async function getDocumentOriginalFile(db, input) {
+  const subjectId = cleanString(input.access.viewerSubjectId ?? null);
+  if (!subjectId || input.access.agentOnly) return null;
+  return await resolveDocumentOriginalFileForSubject(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    subjectId,
+    documentId: input.documentId
+  });
+}
+async function getDocumentForIndexing(db, workspaceId, documentId) {
+  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    const [row] = await scopedDb.select().from(schema.documents).where(
+      and(eq(schema.documents.workspaceId, workspaceId), eq(schema.documents.id, documentId))
     ).limit(1);
     return row ? mapDocument(row) : null;
   });
 }
 async function queueDocumentForReindex(db, workspaceId, documentId, access, organizationAuthorityGranted) {
   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)
-      )
+    const [document] = await scopedDb.select().from(schema.documents).where(
+      and(eq(schema.documents.id, documentId), ...documentAccessConditions(workspaceId, access))
     ).limit(1);
     if (!document) throw new Error(`Document not found: ${documentId}`);
     assertOrganizationDocumentAuthority(document.authorityKind, organizationAuthorityGranted);
@@ -1025,11 +1217,7 @@ async function queueDocumentForReindex(db, workspaceId, documentId, access, orga
       error: null,
       updatedAt: /* @__PURE__ */ new Date()
     }).where(
-      and(
-        eq(schema.documents.workspaceId, workspaceId),
-        eq(schema.documents.id, documentId),
-        ...documentAccessConditions(workspaceId, access)
-      )
+      and(eq(schema.documents.id, documentId), ...documentAccessConditions(workspaceId, access))
     ).returning();
     if (!row) throw new Error(`Document not found: ${documentId}`);
     return mapDocument(row);
@@ -1051,7 +1239,12 @@ async function indexDocumentNow(db, objectStorage, workspaceId, documentId, serv
   );
   if (!loadedDocument) throw new Error(`Document not found: ${documentId}`);
   let document = loadedDocument;
-  const file = await requireReadyFile(db, workspaceId, document.fileId);
+  const file = await requireReadyFile(db, {
+    accountId: document.accountId,
+    workspaceId,
+    subjectId: cleanString(document.createdBy) ?? null,
+    fileId: document.fileId
+  });
   await withDocumentRls(db, workspaceId, access, async (scopedDb) => {
     await scopedDb.update(schema.documents).set({
       status: "indexing",
@@ -1063,7 +1256,11 @@ async function indexDocumentNow(db, objectStorage, workspaceId, documentId, serv
     );
   });
   try {
-    const bytes = await objectStorage.getFileBytes(file);
+    const object = await retryWhileMissing(
+      async () => objectStorage.getObjectBytes(file.objectKey)
+    );
+    if (!object) throw new Error("document source object is missing");
+    const bytes = object.bytes;
     const parsed = await services.parser.parse(bytes, file);
     if (document.curationStatus === "pending") {
       document = await curateDroppedDocument(db, services, document, parsed, file);
@@ -1157,9 +1354,7 @@ async function indexDocumentNow(db, objectStorage, workspaceId, documentId, serv
     if (!failed) throw error;
     return mapDocument(failed);
   }
-  const updated = await getDocument(db, workspaceId, documentId, {
-    viewerSubjectId: document.authoritySubjectId
-  });
+  const updated = await getDocumentForIndexing(db, workspaceId, documentId);
   if (!updated) throw new Error(`Document disappeared after indexing: ${documentId}`);
   return updated;
 }
@@ -1259,6 +1454,9 @@ async function curateDroppedDocument(db, services, document, parsed, file) {
   return updated ?? document;
 }
 async function searchDocuments(db, input, services = createDocumentServices()) {
+  return (await searchDocumentCandidates(db, input, services)).results;
+}
+async function searchDocumentCandidates(db, input, services, relevanceFloor) {
   await assertDocumentAccountWorkspace(db, input.accountId, input.workspaceId);
   const mode = input.mode ?? "hybrid";
   const limit = Math.min(Math.max(input.limit ?? 5, 1), 50);
@@ -1283,13 +1481,34 @@ async function searchDocuments(db, input, services = createDocumentServices()) {
   if (mode === "keyword" || mode === "hybrid") {
     rows.push(...await keywordSearchDocuments(db, input, candidateLimit));
   }
-  return mergeDocumentSearchRows(rows, mode).slice(0, limit);
+  const merged = mergeDocumentSearchRows(rows, mode);
+  return selectDocumentSearchCandidateWindow(merged, limit, relevanceFloor);
+}
+function selectDocumentSearchCandidateWindow(merged, limit, relevanceFloor) {
+  const boundedLimit = Math.min(Math.max(Math.trunc(limit), 1), 50);
+  if (!relevanceFloor) {
+    return { results: merged.slice(0, boundedLimit), belowRelevanceFloor: 0 };
+  }
+  let belowRelevanceFloor = 0;
+  const relevant = merged.filter((result) => {
+    const included = result.vectorScore !== null && result.vectorScore >= relevanceFloor.vectorScore || result.keywordScore !== null && result.keywordScore >= relevanceFloor.keywordScore;
+    if (!included) belowRelevanceFloor += 1;
+    return included;
+  });
+  return { results: relevant.slice(0, boundedLimit), belowRelevanceFloor };
 }
 async function searchEffectiveDocuments(db, input, services = createDocumentServices()) {
   const initiatingSubjectId = cleanString(input.initiatingSubjectId);
   if (!initiatingSubjectId) {
     throw new Error("effective document retrieval requires an initiating subject");
   }
+  const access = await resolveEffectiveDocumentAccess(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    initiatingSubjectId,
+    surface: input.surface,
+    agentAuthority: input.agentAuthority
+  });
   return await searchDocuments(
     db,
     {
@@ -1303,29 +1522,62 @@ async function searchEffectiveDocuments(db, input, services = createDocumentServ
       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 } : {}
-      }
+      access
     },
     services
   );
 }
 async function searchEffectiveKnowledge(db, input, services = createDocumentServices()) {
   const initiatingSubjectId = canonicalEffectiveDocumentSubject(input.initiatingSubjectId);
-  const ranked = await searchEffectiveDocuments(
+  const requestedLimit = Math.min(Math.max(input.limit ?? 5, 1), KNOWLEDGE_SEARCH_MAX_RESULTS);
+  const access = await resolveEffectiveDocumentAccess(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    initiatingSubjectId,
+    surface: input.surface,
+    agentAuthority: input.agentAuthority
+  });
+  const candidateLimit = Math.min(requestedLimit * 4, KNOWLEDGE_SEARCH_MAX_RESULTS);
+  const rankedSelection = await searchDocumentCandidates(
     db,
-    { ...input, initiatingSubjectId, surface: "agent" },
-    services
+    {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      query: input.query,
+      limit: candidateLimit,
+      ...input.baseIds ? { baseIds: input.baseIds } : {},
+      ...input.mode ? { mode: input.mode } : {},
+      ...input.sourceKinds ? { sourceKinds: input.sourceKinds } : {},
+      ...input.aclTags ? { aclTags: input.aclTags } : {},
+      access
+    },
+    services,
+    {
+      vectorScore: KNOWLEDGE_SEARCH_MIN_VECTOR_SCORE,
+      keywordScore: KNOWLEDGE_SEARCH_MIN_KEYWORD_SCORE
+    }
   );
-  if (ranked.length === 0) return { results: [] };
-  const access = { agentOnly: true, viewerSubjectId: initiatingSubjectId };
+  const ranked = rankedSelection.results;
+  if (ranked.length === 0) {
+    return selectKnowledgeSearchResults({
+      candidates: [],
+      rankedCandidateCount: 0,
+      requestedLimit,
+      alreadyBelowRelevanceFloor: rankedSelection.belowRelevanceFloor
+    });
+  }
   const current = await withDocumentAccountRls(
     db,
     input.accountId,
     input.workspaceId,
     access,
-    async (scopedDb) => await scopedDb.select({ chunk: schema.documentChunks, document: schema.documents }).from(schema.documentChunks).innerJoin(schema.documents, eq(schema.documentChunks.documentId, schema.documents.id)).where(
+    async (scopedDb) => await scopedDb.select({
+      chunk: schema.documentChunks,
+      document: schema.documents,
+      citation: googleDriveCitationProjection(input.workspaceId, access),
+      previousChunkId: knowledgePreviousChunkIdProjection(),
+      nextChunkId: knowledgeNextChunkIdProjection()
+    }).from(schema.documentChunks).innerJoin(schema.documents, eq(schema.documentChunks.documentId, schema.documents.id)).where(
       and(
         eq(schema.documents.accountId, input.accountId),
         eq(schema.documentChunks.accountId, input.accountId),
@@ -1339,28 +1591,310 @@ async function searchEffectiveKnowledge(db, input, services = createDocumentServ
     )
   );
   const currentByChunkId = new Map(current.map((row) => [row.chunk.id, row]));
-  return {
-    results: ranked.flatMap((rankedResult) => {
+  return selectKnowledgeSearchResults({
+    rankedCandidateCount: ranked.length,
+    requestedLimit,
+    alreadyBelowRelevanceFloor: rankedSelection.belowRelevanceFloor,
+    candidates: ranked.flatMap((rankedResult) => {
       const row = currentByChunkId.get(rankedResult.chunkId);
       if (!row) return [];
       return [
         {
-          record: knowledgeChunkRecord(row.document, row.chunk),
-          retrieval: {
-            score: rankedResult.score,
-            matchType: rankedResult.matchType,
-            vectorScore: rankedResult.vectorScore,
-            keywordScore: rankedResult.keywordScore
-          }
+          record: knowledgeChunkRecord(row.document, row.chunk, row.citation, {
+            previousChunkId: row.previousChunkId,
+            nextChunkId: row.nextChunkId
+          }),
+          semanticScore: rankedResult.score,
+          matchType: rankedResult.matchType,
+          vectorScore: rankedResult.vectorScore,
+          keywordScore: rankedResult.keywordScore
         }
       ];
     })
+  });
+}
+function selectKnowledgeSearchResults(input) {
+  const requestedLimit = Math.min(
+    Math.max(Math.trunc(input.requestedLimit), 1),
+    KNOWLEDGE_SEARCH_MAX_RESULTS
+  );
+  const nowMs = (input.now ?? /* @__PURE__ */ new Date()).getTime();
+  let belowRelevanceFloor = Math.min(
+    Math.max(0, Math.trunc(input.alreadyBelowRelevanceFloor ?? 0)),
+    KNOWLEDGE_SEARCH_MAX_FLOOR_OMISSIONS
+  );
+  const relevant = [];
+  for (const candidate of input.candidates) {
+    const relevanceSignals = [];
+    if (candidate.vectorScore !== null && candidate.vectorScore >= KNOWLEDGE_SEARCH_MIN_VECTOR_SCORE) {
+      relevanceSignals.push("vector");
+    }
+    if (candidate.keywordScore !== null && candidate.keywordScore >= KNOWLEDGE_SEARCH_MIN_KEYWORD_SCORE) {
+      relevanceSignals.push("keyword");
+    }
+    if (relevanceSignals.length === 0) {
+      belowRelevanceFloor = Math.min(belowRelevanceFloor + 1, KNOWLEDGE_SEARCH_MAX_FLOOR_OMISSIONS);
+      continue;
+    }
+    const freshness = knowledgeFreshness(candidate.record.quality.freshnessAt, nowMs);
+    const qualityAdjustment = freshness === "current" ? 0.02 : freshness === "aging" ? 0.01 : 0;
+    relevant.push({
+      record: candidate.record,
+      retrieval: {
+        score: roundScore(Math.min(1, candidate.semanticScore + qualityAdjustment)),
+        semanticScore: roundScore(candidate.semanticScore),
+        matchType: candidate.matchType,
+        vectorScore: candidate.vectorScore === null ? null : roundScore(candidate.vectorScore),
+        keywordScore: candidate.keywordScore === null ? null : roundScore(candidate.keywordScore),
+        relevanceSignals,
+        freshness,
+        qualityAdjustment,
+        duplicateCount: 0
+      }
+    });
+  }
+  relevant.sort(compareKnowledgeSearchResults);
+  const deduped = [];
+  const byContent = /* @__PURE__ */ new Map();
+  let asDuplicate = 0;
+  for (const result of relevant) {
+    const key = knowledgeTextualContentKey(result.record);
+    const retainedIndex = byContent.get(key);
+    if (retainedIndex === void 0) {
+      byContent.set(key, deduped.length);
+      deduped.push(result);
+      continue;
+    }
+    asDuplicate += 1;
+    const retained = deduped[retainedIndex];
+    retained.retrieval.duplicateCount += 1;
+  }
+  const forLimit = Math.max(0, deduped.length - requestedLimit);
+  const bounded = deduped.slice(0, requestedLimit);
+  let forResponseBudget = 0;
+  let response = knowledgeSearchResponse({
+    results: bounded,
+    rankedCandidateCount: input.rankedCandidateCount,
+    recheckedCandidateCount: input.candidates.length,
+    belowRelevanceFloor,
+    asDuplicate,
+    forLimit,
+    forResponseBudget
+  });
+  while (knowledgeResponseBytes(response) > KNOWLEDGE_SEARCH_MAX_RESPONSE_BYTES) {
+    if (bounded.length === 0) {
+      throw new Error("knowledge search selection facts exceed the response budget");
+    }
+    bounded.pop();
+    forResponseBudget += 1;
+    response = knowledgeSearchResponse({
+      results: bounded,
+      rankedCandidateCount: input.rankedCandidateCount,
+      recheckedCandidateCount: input.candidates.length,
+      belowRelevanceFloor,
+      asDuplicate,
+      forLimit,
+      forResponseBudget
+    });
+  }
+  return response;
+}
+function compareKnowledgeSearchResults(left, right) {
+  return right.retrieval.score - left.retrieval.score || right.retrieval.semanticScore - left.retrieval.semanticScore || (right.retrieval.vectorScore ?? 0) - (left.retrieval.vectorScore ?? 0) || (right.retrieval.keywordScore ?? 0) - (left.retrieval.keywordScore ?? 0) || (left.record.id === right.record.id ? 0 : left.record.id < right.record.id ? -1 : 1);
+}
+function knowledgeFreshness(value, nowMs) {
+  const freshnessMs = Date.parse(value);
+  if (!Number.isFinite(freshnessMs)) return "stale";
+  const ageDays = Math.max(0, (nowMs - freshnessMs) / 864e5);
+  if (ageDays <= 90) return "current";
+  return ageDays <= 365 ? "aging" : "stale";
+}
+function knowledgeTextualContentKey(record) {
+  return createHash("sha256").update("opengeni:knowledge-search-content:v1\0").update(record.title).update("\0").update(
+    JSON.stringify({
+      body: record.content.body,
+      summary: record.content.summary,
+      topics: record.content.topics
+    })
+  ).digest("hex");
+}
+function knowledgeSearchResponse(input) {
+  const selection = {
+    relevanceFloor: {
+      policy: "any_signal",
+      vectorScore: KNOWLEDGE_SEARCH_MIN_VECTOR_SCORE,
+      keywordScore: KNOWLEDGE_SEARCH_MIN_KEYWORD_SCORE
+    },
+    dedupe: { policy: "exact_textual_content" },
+    candidates: {
+      ranked: input.rankedCandidateCount,
+      rechecked: input.recheckedCandidateCount,
+      omittedOnRecheck: Math.max(0, input.rankedCandidateCount - input.recheckedCandidateCount)
+    },
+    omitted: {
+      belowRelevanceFloor: input.belowRelevanceFloor,
+      asDuplicate: input.asDuplicate,
+      forLimit: input.forLimit,
+      forResponseBudget: input.forResponseBudget
+    },
+    budget: {
+      maxResults: KNOWLEDGE_SEARCH_MAX_RESULTS,
+      maxResponseBytes: KNOWLEDGE_SEARCH_MAX_RESPONSE_BYTES,
+      responseBytes: 0,
+      tokenEstimateBytesPerToken: KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN,
+      estimatedTokens: 0,
+      maxEstimatedTokens: Math.ceil(
+        KNOWLEDGE_SEARCH_MAX_RESPONSE_BYTES / KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN
+      )
+    }
+  };
+  const response = {
+    results: [...input.results],
+    selection
+  };
+  for (let index = 0; index < 8; index += 1) {
+    const responseBytes = knowledgeResponseBytes(response);
+    const estimatedTokens = Math.ceil(
+      responseBytes / KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN
+    );
+    if (response.selection.budget.responseBytes === responseBytes && response.selection.budget.estimatedTokens === estimatedTokens) {
+      break;
+    }
+    response.selection.budget.responseBytes = responseBytes;
+    response.selection.budget.estimatedTokens = estimatedTokens;
+  }
+  return response;
+}
+function knowledgeResponseBytes(response) {
+  return Buffer.byteLength(JSON.stringify(response), "utf8");
+}
+function selectKnowledgeBrowseRecords(input) {
+  const entries = input.entries.slice(0, KNOWLEDGE_BROWSE_MAX_LIMIT);
+  const selected = entries.map((entry) => entry.record);
+  let omittedForResponseBudget = 0;
+  let compactedRecordCount = 0;
+  let response = knowledgeBrowseResponse({
+    records: selected,
+    nextCursor: input.hasMoreAfterEntries ? entries.at(-1)?.cursorAfter ?? null : null,
+    hasMore: input.hasMoreAfterEntries,
+    omittedForResponseBudget,
+    compactedRecordCount
+  });
+  while (selected.length > 1 && knowledgeBrowseResponseBytes(response) > KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES) {
+    selected.pop();
+    omittedForResponseBudget += 1;
+    response = knowledgeBrowseResponse({
+      records: selected,
+      nextCursor: entries[selected.length - 1]?.cursorAfter ?? null,
+      hasMore: true,
+      omittedForResponseBudget,
+      compactedRecordCount
+    });
+  }
+  if (selected.length === 1 && knowledgeBrowseResponseBytes(response) > KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES) {
+    selected[0] = compactKnowledgeBrowseRecord(selected[0]);
+    compactedRecordCount = 1;
+    response = knowledgeBrowseResponse({
+      records: selected,
+      nextCursor: omittedForResponseBudget > 0 || input.hasMoreAfterEntries ? entries[0]?.cursorAfter ?? null : null,
+      hasMore: omittedForResponseBudget > 0 || input.hasMoreAfterEntries,
+      omittedForResponseBudget,
+      compactedRecordCount
+    });
+  }
+  if (knowledgeBrowseResponseBytes(response) > KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES) {
+    throw new Error("knowledge browse discovery projection exceeds the response budget");
+  }
+  return response;
+}
+function compactKnowledgeBrowseRecord(record) {
+  const fields = /* @__PURE__ */ new Set([
+    ...record.projection.fields,
+    "content.body",
+    "content.summary",
+    "content.topics",
+    "content.metadata",
+    "provenance.source.uri",
+    "provenance.source.externalId",
+    "provenance.source.title",
+    "provenance.source.author",
+    "provenance.source.version",
+    "provenance.citation"
+  ]);
+  return {
+    ...record,
+    content: {
+      format: "markdown",
+      body: null,
+      summary: null,
+      topics: [],
+      metadata: {}
+    },
+    provenance: {
+      ...record.provenance,
+      source: {
+        ...record.provenance.source,
+        uri: null,
+        externalId: null,
+        title: null,
+        author: null,
+        version: null
+      },
+      citation: null
+    },
+    links: record.links.filter((link) => link.target.kind === "knowledge"),
+    projection: {
+      truncated: true,
+      fields: [...fields].sort()
+    }
   };
 }
+function knowledgeBrowseResponse(input) {
+  const response = {
+    records: [...input.records],
+    nextCursor: input.nextCursor,
+    hasMore: input.hasMore,
+    selection: {
+      omitted: { forResponseBudget: input.omittedForResponseBudget },
+      compactedRecordCount: input.compactedRecordCount,
+      budget: {
+        maxResults: KNOWLEDGE_BROWSE_MAX_LIMIT,
+        maxResponseBytes: KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES,
+        responseBytes: 0,
+        tokenEstimateBytesPerToken: KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN,
+        estimatedTokens: 0,
+        maxEstimatedTokens: Math.ceil(
+          KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES / KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN
+        )
+      }
+    }
+  };
+  for (let index = 0; index < 8; index += 1) {
+    const responseBytes = knowledgeBrowseResponseBytes(response);
+    const estimatedTokens = Math.ceil(
+      responseBytes / KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN
+    );
+    if (response.selection.budget.responseBytes === responseBytes && response.selection.budget.estimatedTokens === estimatedTokens) {
+      break;
+    }
+    response.selection.budget.responseBytes = responseBytes;
+    response.selection.budget.estimatedTokens = estimatedTokens;
+  }
+  return response;
+}
+function knowledgeBrowseResponseBytes(response) {
+  return Buffer.byteLength(JSON.stringify(response), "utf8");
+}
 async function getEffectiveKnowledgeRecord(db, input) {
   const initiatingSubjectId = canonicalEffectiveDocumentSubject(input.initiatingSubjectId);
   const target = parseKnowledgeRecordId(input.id);
-  const access = { agentOnly: true, viewerSubjectId: initiatingSubjectId };
+  const access = await resolveEffectiveDocumentAccess(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    initiatingSubjectId,
+    surface: input.surface ?? "agent",
+    agentAuthority: input.agentAuthority
+  });
   return await withDocumentAccountRls(
     db,
     input.accountId,
@@ -1368,7 +1902,18 @@ async function getEffectiveKnowledgeRecord(db, input) {
     access,
     async (scopedDb) => {
       if (target.kind === "document") {
-        const [document] = await scopedDb.select().from(schema.documents).where(
+        const [row2] = await scopedDb.select({
+          document: schema.documents,
+          citation: googleDriveCitationProjection(input.workspaceId, access),
+          firstChunkId: schema.documentChunks.id
+        }).from(schema.documents).leftJoin(
+          schema.documentChunks,
+          and(
+            eq(schema.documentChunks.accountId, schema.documents.accountId),
+            eq(schema.documentChunks.documentId, schema.documents.id),
+            eq(schema.documentChunks.chunkIndex, 0)
+          )
+        ).where(
           and(
             eq(schema.documents.accountId, input.accountId),
             eq(schema.documents.id, target.id),
@@ -1376,9 +1921,15 @@ async function getEffectiveKnowledgeRecord(db, input) {
             ...documentAccessConditions(input.workspaceId, access)
           )
         ).limit(1);
-        return document ? knowledgeDocumentRecord(document) : null;
+        return row2 ? knowledgeDocumentRecord(row2.document, row2.citation, row2.firstChunkId) : null;
       }
-      const [row] = await scopedDb.select({ chunk: schema.documentChunks, document: schema.documents }).from(schema.documentChunks).innerJoin(schema.documents, eq(schema.documentChunks.documentId, schema.documents.id)).where(
+      const [row] = await scopedDb.select({
+        chunk: schema.documentChunks,
+        document: schema.documents,
+        citation: googleDriveCitationProjection(input.workspaceId, access),
+        previousChunkId: knowledgePreviousChunkIdProjection(),
+        nextChunkId: knowledgeNextChunkIdProjection()
+      }).from(schema.documentChunks).innerJoin(schema.documents, eq(schema.documentChunks.documentId, schema.documents.id)).where(
         and(
           eq(schema.documents.accountId, input.accountId),
           eq(schema.documentChunks.accountId, input.accountId),
@@ -1387,7 +1938,10 @@ async function getEffectiveKnowledgeRecord(db, input) {
           ...documentAccessConditions(input.workspaceId, access)
         )
       ).limit(1);
-      return row ? knowledgeChunkRecord(row.document, row.chunk) : null;
+      return row ? knowledgeChunkRecord(row.document, row.chunk, row.citation, {
+        previousChunkId: row.previousChunkId,
+        nextChunkId: row.nextChunkId
+      }) : null;
     }
   );
 }
@@ -1417,11 +1971,14 @@ async function browseEffectiveKnowledge(db, input) {
     topic,
     sourceKinds
   };
-  const after = input.cursor ? decodeKnowledgeBrowseCursor(input.cursor, cursorScope) : 0n;
-  if (parent && after > 2147483648n) {
-    throw new Error("invalid knowledge browse cursor");
-  }
-  const access = { agentOnly: true, viewerSubjectId: initiatingSubjectId };
+  const topLevelAfter = !parent && input.cursor ? decodeKnowledgeBrowseCursor(input.cursor, cursorScope) : 0n;
+  const access = await resolveEffectiveDocumentAccess(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    initiatingSubjectId,
+    surface: input.surface ?? "agent",
+    agentAuthority: input.agentAuthority
+  });
   return await withDocumentAccountRls(
     db,
     input.accountId,
@@ -1429,7 +1986,7 @@ async function browseEffectiveKnowledge(db, input) {
     access,
     async (scopedDb) => {
       if (parent) {
-        const [authorizedParent] = await scopedDb.select({ id: schema.documents.id }).from(schema.documents).where(
+        const [authorizedParent] = await scopedDb.select({ id: schema.documents.id, indexSequence: schema.documents.indexSequence }).from(schema.documents).where(
           and(
             eq(schema.documents.accountId, input.accountId),
             eq(schema.documents.id, parent.id),
@@ -1437,51 +1994,96 @@ async function browseEffectiveKnowledge(db, input) {
             ...documentAccessConditions(input.workspaceId, access)
           )
         ).limit(1);
-        if (!authorizedParent) return { records: [], nextCursor: null, hasMore: false };
-        const rows2 = await scopedDb.select({ chunk: schema.documentChunks, document: schema.documents }).from(schema.documentChunks).innerJoin(schema.documents, eq(schema.documentChunks.documentId, schema.documents.id)).where(
+        if (!authorizedParent) {
+          return selectKnowledgeBrowseRecords({ entries: [], hasMoreAfterEntries: false });
+        }
+        if (authorizedParent.indexSequence === null) {
+          throw new Error("ready knowledge document is missing its index revision");
+        }
+        const parentCursorScope = {
+          ...cursorScope,
+          parentRevision: authorizedParent.indexSequence.toString()
+        };
+        const after = input.cursor ? decodeKnowledgeBrowseCursor(input.cursor, parentCursorScope) : 0n;
+        if (after > 2147483648n) {
+          throw new Error("invalid knowledge browse cursor");
+        }
+        const rows2 = await scopedDb.select({
+          chunk: schema.documentChunks,
+          document: schema.documents,
+          citation: googleDriveCitationProjection(input.workspaceId, access),
+          previousChunkId: knowledgePreviousChunkIdProjection(),
+          nextChunkId: knowledgeNextChunkIdProjection()
+        }).from(schema.documentChunks).innerJoin(schema.documents, eq(schema.documentChunks.documentId, schema.documents.id)).where(
           and(
             eq(schema.documentChunks.accountId, input.accountId),
             eq(schema.documentChunks.documentId, parent.id),
             gt(schema.documentChunks.chunkIndex, Number(after) - 1),
             eq(schema.documents.status, "ready"),
+            eq(schema.documents.indexSequence, authorizedParent.indexSequence),
             ...documentAccessConditions(input.workspaceId, access)
           )
         ).orderBy(asc(schema.documentChunks.chunkIndex)).limit(limit + 1);
         const hasMore2 = rows2.length > limit;
         const page2 = rows2.slice(0, limit);
-        const last2 = page2.at(-1)?.chunk.chunkIndex;
-        return {
-          records: page2.map((row) => knowledgeChunkRecord(row.document, row.chunk)),
-          nextCursor: hasMore2 && last2 !== void 0 ? encodeKnowledgeBrowseCursor(cursorScope, BigInt(last2 + 1)) : null,
-          hasMore: hasMore2
-        };
+        return selectKnowledgeBrowseRecords({
+          entries: page2.map((row) => ({
+            record: knowledgeChunkRecord(row.document, row.chunk, row.citation, {
+              previousChunkId: row.previousChunkId,
+              nextChunkId: row.nextChunkId
+            }),
+            cursorAfter: encodeKnowledgeBrowseCursor(
+              parentCursorScope,
+              BigInt(row.chunk.chunkIndex + 1)
+            )
+          })),
+          hasMoreAfterEntries: hasMore2
+        });
       }
       const conditions = [
         eq(schema.documents.accountId, input.accountId),
         eq(schema.documents.status, "ready"),
         isNotNull(schema.documents.indexSequence),
-        gt(schema.documents.indexSequence, after),
+        gt(schema.documents.indexSequence, topLevelAfter),
         ...documentAccessConditions(input.workspaceId, access)
       ];
       if (topic) conditions.push(sql`${schema.documents.topics} ? ${topic}`);
       if (sourceKinds.length > 0)
         conditions.push(inArray(schema.documents.sourceKind, sourceKinds));
-      const rows = await scopedDb.select().from(schema.documents).where(and(...conditions)).orderBy(asc(schema.documents.indexSequence)).limit(limit + 1);
+      const rows = await scopedDb.select({
+        document: schema.documents,
+        citation: googleDriveCitationProjection(input.workspaceId, access),
+        firstChunkId: schema.documentChunks.id
+      }).from(schema.documents).leftJoin(
+        schema.documentChunks,
+        and(
+          eq(schema.documentChunks.accountId, schema.documents.accountId),
+          eq(schema.documentChunks.documentId, schema.documents.id),
+          eq(schema.documentChunks.chunkIndex, 0)
+        )
+      ).where(and(...conditions)).orderBy(asc(schema.documents.indexSequence)).limit(limit + 1);
       const hasMore = rows.length > limit;
       const page = rows.slice(0, limit);
-      const last = page.at(-1)?.indexSequence;
-      return {
-        records: page.map(knowledgeDocumentRecord),
-        nextCursor: hasMore && last !== void 0 && last !== null ? encodeKnowledgeBrowseCursor(cursorScope, last) : null,
-        hasMore
-      };
+      return selectKnowledgeBrowseRecords({
+        entries: page.map((row) => {
+          if (row.document.indexSequence === null) {
+            throw new Error("ready knowledge document is missing its index revision");
+          }
+          return {
+            record: knowledgeDocumentRecord(row.document, row.citation, row.firstChunkId),
+            cursorAfter: encodeKnowledgeBrowseCursor(cursorScope, row.document.indexSequence)
+          };
+        }),
+        hasMoreAfterEntries: hasMore
+      });
     }
   );
 }
 function encodeKnowledgeBrowseCursor(scope, position) {
   if (position < 0n) throw new Error("knowledge browse cursor position is invalid");
+  const version = knowledgeBrowseCursorVersion(scope);
   return Buffer.from(
-    JSON.stringify({ v: 1, s: knowledgeBrowseCursorScope(scope), q: position.toString() }),
+    JSON.stringify({ v: version, s: knowledgeBrowseCursorScope(scope), q: position.toString() }),
     "utf8"
   ).toString("base64url");
 }
@@ -1493,7 +2095,8 @@ function decodeKnowledgeBrowseCursor(value, scope) {
     const bytes = Buffer.from(value, "base64url");
     if (bytes.toString("base64url") !== value) throw new Error("cursor encoding");
     const parsed = JSON.parse(bytes.toString("utf8"));
-    if (Object.keys(parsed).sort().join(",") !== "q,s,v" || parsed.v !== 1 || typeof parsed.s !== "string" || typeof parsed.q !== "string" || !/^(0|[1-9][0-9]*)$/.test(parsed.q)) {
+    const expectedVersion = knowledgeBrowseCursorVersion(scope);
+    if (Object.keys(parsed).sort().join(",") !== "q,s,v" || parsed.v !== expectedVersion || typeof parsed.s !== "string" || typeof parsed.q !== "string" || !/^(0|[1-9][0-9]*)$/.test(parsed.q)) {
       throw new Error("cursor payload");
     }
     if (parsed.s !== knowledgeBrowseCursorScope(scope)) {
@@ -1510,7 +2113,17 @@ function decodeKnowledgeBrowseCursor(value, scope) {
   }
 }
 function knowledgeBrowseCursorScope(scope) {
-  return createHash("sha256").update("opengeni:knowledge-browse-cursor:v1\0").update(scope.accountId).update("\0").update(scope.workspaceId).update("\0").update(canonicalEffectiveDocumentSubject(scope.initiatingSubjectId)).update("\0").update(scope.parentId ?? "").update("\0").update(scope.topic ?? "").update("\0").update([...scope.sourceKinds].sort().join("\0")).digest("hex");
+  const version = knowledgeBrowseCursorVersion(scope);
+  const hash = createHash("sha256").update(`opengeni:knowledge-browse-cursor:v${version}\0`).update(scope.accountId).update("\0").update(scope.workspaceId).update("\0").update(canonicalEffectiveDocumentSubject(scope.initiatingSubjectId)).update("\0").update(scope.parentId ?? "").update("\0");
+  if (version === 2) hash.update(scope.parentRevision).update("\0");
+  return hash.update(scope.topic ?? "").update("\0").update([...scope.sourceKinds].sort().join("\0")).digest("hex");
+}
+function knowledgeBrowseCursorVersion(scope) {
+  if (!scope.parentId) return 1;
+  if (!scope.parentRevision || !/^[1-9][0-9]*$/.test(scope.parentRevision)) {
+    throw new Error("knowledge browse parent cursor requires an exact document revision");
+  }
+  return 2;
 }
 function parseKnowledgeRecordId(value) {
   const match = /^(document|document_chunk):([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/iu.exec(
@@ -1519,7 +2132,7 @@ function parseKnowledgeRecordId(value) {
   if (!match) throw new Error("invalid knowledge record id");
   return { kind: match[1], id: match[2].toLowerCase() };
 }
-function knowledgeDocumentRecord(document) {
+function knowledgeDocumentRecord(document, citation = null, firstChunkId = null) {
   if (!document.indexedAt) throw new Error(`Ready document is missing indexed_at: ${document.id}`);
   const projected = projectKnowledgeRecord({
     title: document.title,
@@ -1537,15 +2150,27 @@ function knowledgeDocumentRecord(document) {
     authority: { kind: normalizeDocumentAuthorityKind(document.authorityKind) },
     provenance: {
       source: projected.source,
-      indexedAt: document.indexedAt.toISOString()
+      indexedAt: document.indexedAt.toISOString(),
+      citation: parseKnowledgeProviderCitation(citation)
     },
     lifecycle: { state: "active", updatedAt: document.updatedAt.toISOString() },
     quality: knowledgeQuality(document),
-    links: knowledgeSourceLinks(projected.source.uri),
+    links: [
+      ...firstChunkId ? [
+        {
+          relation: "contents",
+          target: {
+            kind: "knowledge",
+            id: `document_chunk:${firstChunkId}`
+          }
+        }
+      ] : [],
+      ...knowledgeSourceLinks(projected.source.uri)
+    ],
     projection: projected.projection
   };
 }
-function knowledgeChunkRecord(document, chunk) {
+function knowledgeChunkRecord(document, chunk, citation = null, traversal = { previousChunkId: null, nextChunkId: null }) {
   if (!document.indexedAt) throw new Error(`Ready document is missing indexed_at: ${document.id}`);
   const projected = projectKnowledgeRecord({
     title: document.title,
@@ -1563,12 +2188,34 @@ function knowledgeChunkRecord(document, chunk) {
     authority: { kind: normalizeDocumentAuthorityKind(document.authorityKind) },
     provenance: {
       source: projected.source,
-      indexedAt: document.indexedAt.toISOString()
+      indexedAt: document.indexedAt.toISOString(),
+      citation: parseKnowledgeProviderCitation(citation)
     },
     lifecycle: { state: "active", updatedAt: document.updatedAt.toISOString() },
     quality: knowledgeQuality(document),
     links: [
-      { relation: "parent", target: { kind: "knowledge", id: `document:${document.id}` } },
+      {
+        relation: "parent",
+        target: { kind: "knowledge", id: `document:${document.id}` }
+      },
+      ...traversal.previousChunkId ? [
+        {
+          relation: "previous",
+          target: {
+            kind: "knowledge",
+            id: `document_chunk:${traversal.previousChunkId}`
+          }
+        }
+      ] : [],
+      ...traversal.nextChunkId ? [
+        {
+          relation: "next",
+          target: {
+            kind: "knowledge",
+            id: `document_chunk:${traversal.nextChunkId}`
+          }
+        }
+      ] : [],
       ...knowledgeSourceLinks(projected.source.uri)
     ],
     projection: projected.projection
@@ -1598,6 +2245,28 @@ function knowledgeQuality(document) {
 function knowledgeSourceLinks(sourceUri) {
   return sourceUri ? [{ relation: "source", target: { kind: "external", uri: sourceUri } }] : [];
 }
+function knowledgePreviousChunkIdProjection() {
+  return sql`(
+    select knowledge_previous_chunk.id
+    from document_chunks knowledge_previous_chunk
+    where knowledge_previous_chunk.account_id = ${schema.documentChunks.accountId}
+      and knowledge_previous_chunk.document_id = ${schema.documentChunks.documentId}
+      and knowledge_previous_chunk.chunk_index < ${schema.documentChunks.chunkIndex}
+    order by knowledge_previous_chunk.chunk_index desc
+    limit 1
+  )`;
+}
+function knowledgeNextChunkIdProjection() {
+  return sql`(
+    select knowledge_next_chunk.id
+    from document_chunks knowledge_next_chunk
+    where knowledge_next_chunk.account_id = ${schema.documentChunks.accountId}
+      and knowledge_next_chunk.document_id = ${schema.documentChunks.documentId}
+      and knowledge_next_chunk.chunk_index > ${schema.documentChunks.chunkIndex}
+    order by knowledge_next_chunk.chunk_index asc
+    limit 1
+  )`;
+}
 async function vectorSearchDocuments(db, input, limit, services) {
   const queryEmbedding = await services.embedder.embedQuery(input.query);
   validateEmbedding(queryEmbedding, services.embedder.dimensions, services.embedder.model);
@@ -1629,8 +2298,9 @@ async function vectorSearchDocuments(db, input, limit, services) {
       authorityKind: schema.documents.authorityKind,
       authorityWorkspaceId: schema.documents.authorityWorkspaceId,
       authoritySubjectId: schema.documents.authoritySubjectId,
+      citation: googleDriveCitationProjection(input.workspaceId, input.access),
       distance
-    }).from(schema.documentChunks).innerJoin(schema.documents, eq(schema.documentChunks.documentId, schema.documents.id)).where(and(...documentSearchConditions(input, services.embedder.model))).orderBy(distance).limit(limit)
+    }).from(schema.documentChunks).innerJoin(schema.documents, eq(schema.documentChunks.documentId, schema.documents.id)).where(and(...documentSearchConditions(input, services.embedder.model))).orderBy(distance, asc(schema.documentChunks.id)).limit(limit)
   );
   return rows.map((row) => ({
     ...mapSearchRowBase(row),
@@ -1667,13 +2337,14 @@ async function keywordSearchDocuments(db, input, limit) {
       authorityKind: schema.documents.authorityKind,
       authorityWorkspaceId: schema.documents.authorityWorkspaceId,
       authoritySubjectId: schema.documents.authoritySubjectId,
+      citation: googleDriveCitationProjection(input.workspaceId, input.access),
       rank
     }).from(schema.documentChunks).innerJoin(schema.documents, eq(schema.documentChunks.documentId, schema.documents.id)).where(
       and(
         ...documentSearchConditions(input),
         sql`to_tsvector('simple', ${schema.documentChunks.text}) @@ plainto_tsquery('simple', ${input.query})`
       )
-    ).orderBy(desc(rank)).limit(limit)
+    ).orderBy(desc(rank), asc(schema.documentChunks.id)).limit(limit)
   );
   return rows.map((row) => ({
     ...mapSearchRowBase(row),
@@ -1708,7 +2379,8 @@ async function getDocumentChunk(db, accountId, workspaceId, chunkId, access) {
       aclTags: schema.documents.aclTags,
       authorityKind: schema.documents.authorityKind,
       authorityWorkspaceId: schema.documents.authorityWorkspaceId,
-      authoritySubjectId: schema.documents.authoritySubjectId
+      authoritySubjectId: schema.documents.authoritySubjectId,
+      citation: googleDriveCitationProjection(workspaceId, access)
     }).from(schema.documentChunks).innerJoin(schema.documents, eq(schema.documentChunks.documentId, schema.documents.id)).where(
       and(
         eq(schema.documents.accountId, accountId),
@@ -1768,6 +2440,21 @@ async function assertDocumentAccountWorkspace(db, accountId, workspaceId) {
   }
   return context;
 }
+async function resolveEffectiveDocumentAccess(_db, input) {
+  if (input.surface === "human") {
+    return { viewerSubjectId: input.initiatingSubjectId };
+  }
+  return {
+    agentOnly: true,
+    viewerSubjectId: input.initiatingSubjectId,
+    authorizedPersonalAttempt: input.agentAuthority ? {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      sessionId: input.agentAuthority.sessionId,
+      attemptId: input.agentAuthority.attemptId
+    } : void 0
+  };
+}
 function documentAccessConditions(workspaceId, access) {
   const organization = eq(schema.documents.authorityKind, "organization");
   const workspace = and(
@@ -1775,20 +2462,45 @@ function documentAccessConditions(workspaceId, access) {
     eq(schema.documents.authorityWorkspaceId, workspaceId)
   );
   const viewer = cleanString(access?.viewerSubjectId ?? null);
+  const personalAttempt = access?.authorizedPersonalAttempt;
+  const authorizedPersonal = personalAttempt ? sql`${schema.documents.id} IN (
+        SELECT resolve_session_attempt_personal_document_reads(
+          ${personalAttempt.accountId}::uuid,
+          ${personalAttempt.workspaceId}::uuid,
+          ${personalAttempt.sessionId}::uuid,
+          ${personalAttempt.attemptId}::uuid
+        )
+      )` : sql`false`;
   const personal = viewer ? and(
     eq(schema.documents.authorityKind, "personal"),
-    eq(schema.documents.authorityWorkspaceId, workspaceId),
-    eq(schema.documents.authoritySubjectId, viewer)
+    eq(schema.documents.authoritySubjectId, viewer),
+    access?.agentOnly ? or(
+      and(
+        isNull(schema.documents.authorityId),
+        eq(schema.documents.authorityWorkspaceId, workspaceId)
+      ),
+      and(isNotNull(schema.documents.authorityId), authorizedPersonal)
+    ) ?? authorizedPersonal : or(
+      eq(schema.documents.authorityWorkspaceId, workspaceId),
+      isNull(schema.documents.authorityWorkspaceId)
+    ) ?? eq(schema.documents.authorityWorkspaceId, workspaceId)
   ) : void 0;
   const authority = viewer ? or(organization, workspace, personal) ?? organization : or(organization, workspace) ?? organization;
+  const viewerSql = viewer ? sql`${viewer}` : sql`NULL::text`;
+  const providerAuthorization = sql`google_drive_file_authorized(
+    ${schema.documents.accountId},
+    ${workspaceId}::uuid,
+    ${viewerSql},
+    ${schema.documents.fileId}
+  )`;
   if (access?.agentOnly) {
-    return [eq(schema.documents.agentAccess, true), authority];
+    return [eq(schema.documents.agentAccess, true), authority, providerAuthorization];
   }
-  return [authority];
+  return [authority, providerAuthorization];
 }
 function documentMatchesAccess(document, workspaceId, access) {
   if (access?.agentOnly) {
-    return document.agentAccess && canViewDocument(document, access.viewerSubjectId, workspaceId);
+    return document.agentAccess && (document.authorityKind !== "personal" || document.authorityId === null) && canViewDocument(document, access.viewerSubjectId, workspaceId);
   }
   return canViewDocument(document, access?.viewerSubjectId, workspaceId);
 }
@@ -1806,16 +2518,16 @@ function canViewDocument(document, viewerSubjectId, workspaceId) {
     return document.authorityWorkspaceId === null && document.authoritySubjectId === null;
   }
   const normalizedWorkspaceId = cleanString(workspaceId ?? null);
-  if (!normalizedWorkspaceId || document.authorityWorkspaceId !== normalizedWorkspaceId) {
+  if (!normalizedWorkspaceId) {
     return false;
   }
   if (document.authorityKind === "workspace") {
-    return document.authoritySubjectId === null;
+    return document.authorityWorkspaceId === normalizedWorkspaceId && document.authoritySubjectId === null;
   }
   if (document.authorityKind === "personal") {
     const authoritySubjectId = canonicalDocumentAuthoritySubject(document.authoritySubjectId);
     const viewer = canonicalDocumentAuthoritySubject(viewerSubjectId);
-    return !!authoritySubjectId && authoritySubjectId === viewer;
+    return !!authoritySubjectId && authoritySubjectId === viewer && (document.authorityWorkspaceId === null || document.authorityWorkspaceId === normalizedWorkspaceId);
   }
   return false;
 }
@@ -1863,9 +2575,24 @@ function mapSearchRowBase(row) {
     aclTags: cleanStringArray(row.aclTags),
     authorityKind: normalizeDocumentAuthorityKind(row.authorityKind),
     authorityWorkspaceId: row.authorityWorkspaceId,
-    authoritySubjectId: row.authoritySubjectId
+    authoritySubjectId: row.authoritySubjectId,
+    citation: parseKnowledgeProviderCitation(row.citation)
   };
 }
+function googleDriveCitationProjection(workspaceId, access) {
+  const viewer = cleanString(access?.viewerSubjectId ?? null);
+  const viewerSql = viewer ? sql`${viewer}` : sql`NULL::text`;
+  return sql`google_drive_document_citation(
+    ${schema.documents.accountId},
+    ${workspaceId}::uuid,
+    ${viewerSql},
+    ${schema.documents.id},
+    ${schema.documents.fileId}
+  )`;
+}
+function parseKnowledgeProviderCitation(value) {
+  return value === null || value === void 0 ? null : KnowledgeProviderCitation.parse(value);
+}
 function mergeDocumentSearchRows(rows, mode) {
   const byChunk = /* @__PURE__ */ new Map();
   for (const row of rows) {
@@ -1890,7 +2617,7 @@ function mergeDocumentSearchRows(rows, mode) {
       matchType
     };
   }).sort(
-    (left, right) => right.score - left.score || (right.vectorScore ?? 0) - (left.vectorScore ?? 0) || (right.keywordScore ?? 0) - (left.keywordScore ?? 0) || left.chunkIndex - right.chunkIndex
+    (left, right) => right.score - left.score || (right.vectorScore ?? 0) - (left.vectorScore ?? 0) || (right.keywordScore ?? 0) - (left.keywordScore ?? 0) || left.chunkIndex - right.chunkIndex || (left.chunkId === right.chunkId ? 0 : left.chunkId < right.chunkId ? -1 : 1)
   );
 }
 function combinedSearchScore(mode, vectorScore, keywordScore, matchType) {
@@ -1952,10 +2679,16 @@ function deterministicEmbedding(text, dimensions = DEFAULT_DOCUMENT_EMBEDDING_DI
   const norm = Math.hypot(...values) || 1;
   return values.map((value) => Number((value / norm).toFixed(6)));
 }
-async function requireReadyFile(db, workspaceId, fileId) {
-  const file = await requireFile(db, workspaceId, fileId);
+async function requireReadyFile(db, input) {
+  const [file] = await getFilesForSubject(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId,
+    fileIds: [input.fileId]
+  });
+  if (!file) throw new Error(`File not found: ${input.fileId}`);
   if (file.status !== "ready") {
-    throw new Error(`File ${fileId} is ${file.status}`);
+    throw new Error(`File ${input.fileId} is ${file.status}`);
   }
   return file;
 }
@@ -2071,6 +2804,7 @@ function mapDocument(row) {
     authorityKind: normalizeDocumentAuthorityKind(row.authorityKind),
     authorityWorkspaceId: row.authorityWorkspaceId,
     authoritySubjectId: row.authoritySubjectId,
+    authorityId: row.authorityId,
     visibility: normalizeDocumentVisibility(row.visibility),
     createdBy: row.createdBy,
     agentAccess: row.agentAccess,
@@ -2175,10 +2909,14 @@ export {
   getDocument,
   getDocumentBase,
   getDocumentChunk,
+  getDocumentForIndexing,
   getDocumentInventory,
+  getDocumentOriginalFile,
   getEffectiveKnowledgeRecord,
   heuristicCuration,
   indexDocumentNow,
+  listAccessibleDocuments,
+  listDocumentAuthorityReclassifications,
   listDocumentBases,
   listDocumentBasesEnsuringDefault,
   listDocuments,
@@ -2188,9 +2926,15 @@ export {
   parseDocumentBytes,
   projectKnowledgeRecord,
   queueDocumentForReindex,
+  reclassifyDocumentAuthority,
   resolveDocumentAuthority,
+  resolveEffectiveDocumentAccess,
+  runDocumentDefaultCollectionBackfill,
   searchDocuments,
   searchEffectiveDocuments,
-  searchEffectiveKnowledge
+  searchEffectiveKnowledge,
+  selectDocumentSearchCandidateWindow,
+  selectKnowledgeBrowseRecords,
+  selectKnowledgeSearchResults
 };
 //# sourceMappingURL=index.js.map