@opengeni/documents 0.5.18 → 0.5.38

package/dist/index.js

@@ -8,9 +8,185 @@ import {
   withWorkspaceSubjectRls
 } from "@opengeni/db";
 import * as schema from "@opengeni/db/schema";
-import { LiteParse } from "@llamaindex/liteparse";
-import { and, asc, desc, eq, inArray, or, sql } from "drizzle-orm";
-import OpenAI from "openai";
+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";
+
+// src/knowledge-projection.ts
+import {
+  KNOWLEDGE_BODY_MAX_BYTES,
+  KNOWLEDGE_METADATA_MAX_BYTES,
+  KNOWLEDGE_METADATA_MAX_DEPTH,
+  KNOWLEDGE_METADATA_MAX_ITEMS,
+  KNOWLEDGE_SOURCE_STRING_MAX_BYTES,
+  KNOWLEDGE_SOURCE_URI_MAX_BYTES,
+  KNOWLEDGE_SUMMARY_MAX_BYTES,
+  KNOWLEDGE_TITLE_MAX_BYTES,
+  KNOWLEDGE_TOPIC_MAX_BYTES,
+  KNOWLEDGE_TOPICS_MAX_ITEMS
+} from "@opengeni/contracts";
+var utf8Bytes = (value) => Buffer.byteLength(value, "utf8");
+function truncateUtf8(value, maxBytes) {
+  if (utf8Bytes(value) <= maxBytes) return { value, truncated: false };
+  let low = 0;
+  let high = value.length;
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    const end2 = middle > 0 && middle < value.length && /[\uD800-\uDBFF]/u.test(value[middle - 1]) ? middle - 1 : middle;
+    if (utf8Bytes(value.slice(0, end2)) <= maxBytes) low = middle;
+    else high = middle - 1;
+  }
+  let end = low;
+  if (end > 0 && end < value.length && /[\uD800-\uDBFF]/u.test(value[end - 1])) end -= 1;
+  while (end > 0 && utf8Bytes(value.slice(0, end)) > maxBytes) end -= 1;
+  return { value: value.slice(0, end), truncated: true };
+}
+function projectNullableString(value, maxBytes, field, fields) {
+  if (value === null) return null;
+  const projected = truncateUtf8(value, maxBytes);
+  if (projected.truncated) fields.add(field);
+  return projected.value;
+}
+function projectSourceUri(value, fields) {
+  if (value === null || value === "") return null;
+  if (utf8Bytes(value) > KNOWLEDGE_SOURCE_URI_MAX_BYTES) {
+    fields.add("provenance.source.uri");
+    return null;
+  }
+  return value;
+}
+function projectTopics(value, fields) {
+  if (!Array.isArray(value)) {
+    if (value !== null && value !== void 0) fields.add("content.topics");
+    return [];
+  }
+  const result = [];
+  for (const candidate of value) {
+    if (result.length >= KNOWLEDGE_TOPICS_MAX_ITEMS) {
+      fields.add("content.topics");
+      break;
+    }
+    if (typeof candidate !== "string") {
+      fields.add("content.topics");
+      continue;
+    }
+    const projected = truncateUtf8(candidate, KNOWLEDGE_TOPIC_MAX_BYTES);
+    if (projected.truncated) fields.add("content.topics");
+    result.push(projected.value);
+  }
+  return result;
+}
+function projectMetadata(value) {
+  let remainingItems = KNOWLEDGE_METADATA_MAX_ITEMS;
+  let truncated = false;
+  const visit = (candidate, depth) => {
+    if (remainingItems <= 0 || depth > KNOWLEDGE_METADATA_MAX_DEPTH) {
+      truncated = true;
+      return void 0;
+    }
+    remainingItems -= 1;
+    if (candidate === null || typeof candidate === "boolean" || typeof candidate === "number" && Number.isFinite(candidate)) {
+      return candidate;
+    }
+    if (typeof candidate === "string") {
+      const projected = truncateUtf8(candidate, KNOWLEDGE_SOURCE_STRING_MAX_BYTES);
+      if (projected.truncated) truncated = true;
+      return projected.value;
+    }
+    if (Array.isArray(candidate)) {
+      const result2 = [];
+      for (const item of candidate) {
+        const projected = visit(item, depth + 1);
+        if (projected === void 0) break;
+        result2.push(projected);
+      }
+      return result2;
+    }
+    if (candidate && typeof candidate === "object") {
+      const result2 = {};
+      for (const key of Object.keys(candidate).sort()) {
+        if (utf8Bytes(key) > KNOWLEDGE_TOPIC_MAX_BYTES) {
+          truncated = true;
+          continue;
+        }
+        const projected = visit(candidate[key], depth + 1);
+        if (projected === void 0) break;
+        result2[key] = projected;
+      }
+      return result2;
+    }
+    truncated = true;
+    return void 0;
+  };
+  const root = visit(value, 0);
+  let result = root && typeof root === "object" && !Array.isArray(root) ? root : {};
+  if (result !== root) truncated = true;
+  const bounded = {};
+  for (const key of Object.keys(result).sort()) {
+    bounded[key] = result[key];
+    if (utf8Bytes(JSON.stringify(bounded)) > KNOWLEDGE_METADATA_MAX_BYTES) {
+      delete bounded[key];
+      truncated = true;
+      break;
+    }
+  }
+  result = bounded;
+  return { value: result, truncated };
+}
+function projectKnowledgeRecord(input) {
+  const fields = /* @__PURE__ */ new Set();
+  const title = truncateUtf8(input.title, KNOWLEDGE_TITLE_MAX_BYTES);
+  if (title.truncated) fields.add("title");
+  const metadata = projectMetadata(input.metadata);
+  if (metadata.truncated) fields.add("content.metadata");
+  const source = {
+    ...input.source,
+    uri: projectSourceUri(input.source.uri, fields),
+    externalId: projectNullableString(
+      input.source.externalId,
+      KNOWLEDGE_SOURCE_STRING_MAX_BYTES,
+      "provenance.source.externalId",
+      fields
+    ),
+    title: projectNullableString(
+      input.source.title,
+      KNOWLEDGE_SOURCE_STRING_MAX_BYTES,
+      "provenance.source.title",
+      fields
+    ),
+    author: projectNullableString(
+      input.source.author,
+      KNOWLEDGE_SOURCE_STRING_MAX_BYTES,
+      "provenance.source.author",
+      fields
+    ),
+    version: projectNullableString(
+      input.source.version,
+      KNOWLEDGE_SOURCE_STRING_MAX_BYTES,
+      "provenance.source.version",
+      fields
+    )
+  };
+  return {
+    title: title.value,
+    content: {
+      format: "markdown",
+      body: projectNullableString(input.body, KNOWLEDGE_BODY_MAX_BYTES, "content.body", fields),
+      summary: projectNullableString(
+        input.summary,
+        KNOWLEDGE_SUMMARY_MAX_BYTES,
+        "content.summary",
+        fields
+      ),
+      topics: projectTopics(input.topics, fields),
+      metadata: metadata.value
+    },
+    source,
+    projection: { truncated: fields.size > 0, fields: [...fields].sort() }
+  };
+}
+
+// src/index.ts
 var DEFAULT_DOCUMENT_PARSER = "liteparse";
 var DEFAULT_DOCUMENT_EMBEDDING_MODEL = "text-embedding-3-large";
 var DEFAULT_DOCUMENT_EMBEDDING_DIMENSIONS = 3072;
@@ -19,6 +195,7 @@ var DEFAULT_DOCUMENT_CHUNK_OVERLAP = 160;
 var DEFAULT_DOCUMENT_CURATION_MODEL = "gpt-4o-mini";
 var DOCUMENT_CURATION_MAX_INPUT_CHARS = 24e3;
 var DOCUMENT_AUTHORITY_SUBJECT_MAX_BYTES = 1024;
+var DOCUMENT_INDEX_CHECKPOINT_MAX_CHARS = 1024;
 var DOCUMENT_CURATION_AUTO_FILE_CONFIDENCE = 0.75;
 var DEFAULT_BASE_NAME = "Default";
 var DEFAULT_BASE_DESCRIPTION = "Default base for dropped files and notes.";
@@ -44,6 +221,7 @@ var LiteParseDocumentParser = class {
   }
   async parseWithLiteParse(bytes) {
     return await this.enqueueParse(async () => {
+      const { LiteParse } = await import("@llamaindex/liteparse");
       const parser = new LiteParse({ ocrEnabled: true, numWorkers: 1 });
       const result = await parser.parse(Buffer.from(bytes), true);
       const text = typeof result?.text === "string" ? result.text : "";
@@ -85,7 +263,7 @@ var RecursiveTextChunker = class {
   }
 };
 var OpenAIEmbeddingProvider = class {
-  client = null;
+  clientPromise = null;
   apiKey;
   baseURL;
   constructor(args) {
@@ -105,7 +283,7 @@ var OpenAIEmbeddingProvider = class {
     const out = [];
     for (let start = 0; start < texts.length; start += 64) {
       const batch = texts.slice(start, start + 64);
-      const response = await this.openai().embeddings.create({
+      const response = await (await this.openai()).embeddings.create({
         model: this.model,
         input: batch,
         dimensions: this.dimensions
@@ -123,17 +301,19 @@ var OpenAIEmbeddingProvider = class {
     }
     return embedding;
   }
-  openai() {
+  async openai() {
     if (!this.apiKey) {
       throw new Error("OpenAI document embeddings require an API key");
     }
-    this.client ??= new OpenAI({
-      apiKey: this.apiKey,
-      ...this.baseURL ? { baseURL: this.baseURL } : {},
-      ...this.defaultQuery ? { defaultQuery: this.defaultQuery } : {},
-      ...this.defaultHeaders ? { defaultHeaders: this.defaultHeaders } : {}
-    });
-    return this.client;
+    this.clientPromise ??= import("openai").then(
+      ({ default: OpenAIClient }) => new OpenAIClient({
+        apiKey: this.apiKey,
+        ...this.baseURL ? { baseURL: this.baseURL } : {},
+        ...this.defaultQuery ? { defaultQuery: this.defaultQuery } : {},
+        ...this.defaultHeaders ? { defaultHeaders: this.defaultHeaders } : {}
+      })
+    );
+    return await this.clientPromise;
   }
 };
 var DeterministicEmbeddingProvider = class {
@@ -196,7 +376,7 @@ var CURATION_SYSTEM_PROMPT = [
   "well, return targetBaseId null and confidence 0. Respond with JSON only."
 ].join(" ");
 var OpenAICurationProvider = class {
-  client = null;
+  clientPromise = null;
   apiKey;
   baseURL;
   defaultHeaders;
@@ -210,7 +390,7 @@ var OpenAICurationProvider = class {
     this.model = args.model ?? DEFAULT_DOCUMENT_CURATION_MODEL;
   }
   async curate(input) {
-    const response = await this.openai().chat.completions.create({
+    const response = await (await this.openai()).chat.completions.create({
       model: this.model,
       response_format: { type: "json_object" },
       messages: [
@@ -232,17 +412,19 @@ var OpenAICurationProvider = class {
     }
     return parseCurationOutcome(raw, input.bases);
   }
-  openai() {
+  async openai() {
     if (!this.apiKey) {
       throw new Error("OpenAI document curation requires an API key");
     }
-    this.client ??= new OpenAI({
-      apiKey: this.apiKey,
-      ...this.baseURL ? { baseURL: this.baseURL } : {},
-      ...this.defaultQuery ? { defaultQuery: this.defaultQuery } : {},
-      ...this.defaultHeaders ? { defaultHeaders: this.defaultHeaders } : {}
-    });
-    return this.client;
+    this.clientPromise ??= import("openai").then(
+      ({ default: OpenAIClient }) => new OpenAIClient({
+        apiKey: this.apiKey,
+        ...this.baseURL ? { baseURL: this.baseURL } : {},
+        ...this.defaultQuery ? { defaultQuery: this.defaultQuery } : {},
+        ...this.defaultHeaders ? { defaultHeaders: this.defaultHeaders } : {}
+      })
+    );
+    return await this.clientPromise;
   }
 };
 function parseCurationOutcome(raw, bases) {
@@ -534,15 +716,24 @@ async function addDocumentToBase(db, input) {
       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 knowledgeSourceIdentity = cleanString(input.knowledgeSourceIdentity ?? null);
+      if (knowledgeSourceIdentity && knowledgeSourceIdentity.length > 512) {
+        throw new Error("knowledge source document identity exceeds 512 characters");
+      }
       const now = /* @__PURE__ */ new Date();
       const [existing] = await scopedDb.select().from(schema.documents).where(
         and(
           eq(schema.documents.workspaceId, input.workspaceId),
-          eq(schema.documents.baseId, input.baseId),
-          eq(schema.documents.fileId, input.fileId)
+          ...knowledgeSourceIdentity ? [eq(schema.documents.knowledgeSourceIdentity, knowledgeSourceIdentity)] : [
+            eq(schema.documents.baseId, input.baseId),
+            eq(schema.documents.fileId, input.fileId)
+          ]
         )
       ).limit(1);
       if (existing) {
+        if (knowledgeSourceIdentity && existing.fileId !== input.fileId) {
+          throw new Error("knowledge source document identity is bound to different content");
+        }
         if (!documentMatchesAccess(existing, input.workspaceId, input.access)) {
           throw new Error(`Document not found: ${existing.id}`);
         }
@@ -587,6 +778,7 @@ async function addDocumentToBase(db, input) {
         sourceCreatedAt: parseOptionalDate(input.sourceCreatedAt),
         sourceUpdatedAt: parseOptionalDate(input.sourceUpdatedAt),
         sourceVersion: cleanString(input.sourceVersion) ?? null,
+        knowledgeSourceIdentity,
         aclTags: cleanStringArray(input.aclTags),
         authorityKind: authority.kind,
         authorityWorkspaceId: authority.workspaceId,
@@ -630,7 +822,7 @@ async function moveDocumentToBase(db, input) {
         and(
           eq(schema.documents.workspaceId, input.workspaceId),
           eq(schema.documents.baseId, targetBaseId),
-          eq(schema.documents.fileId, row.fileId)
+          ...row.knowledgeSourceIdentity ? [eq(schema.documents.knowledgeSourceIdentity, row.knowledgeSourceIdentity)] : [eq(schema.documents.fileId, row.fileId)]
         )
       ).limit(1);
       if (conflict) {
@@ -710,6 +902,101 @@ async function listDocuments(db, workspaceId, baseId, access) {
     return rows.map(mapDocument);
   });
 }
+async function listEffectiveIndexedDocuments(db, input) {
+  const initiatingSubjectId = canonicalEffectiveDocumentSubject(input.initiatingSubjectId);
+  const limit = input.limit ?? 50;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+    throw new Error("indexed document list limit must be between 1 and 100");
+  }
+  const afterSequence = input.checkpoint ? decodeDocumentIndexCheckpoint(input.checkpoint, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    initiatingSubjectId
+  }) : 0n;
+  const access = {
+    agentOnly: true,
+    viewerSubjectId: initiatingSubjectId
+  };
+  const rows = await withDocumentAccountRls(
+    db,
+    input.accountId,
+    input.workspaceId,
+    access,
+    async (scopedDb) => await scopedDb.select().from(schema.documents).where(
+      and(
+        eq(schema.documents.accountId, input.accountId),
+        eq(schema.documents.status, "ready"),
+        isNotNull(schema.documents.indexSequence),
+        gt(schema.documents.indexSequence, afterSequence),
+        ...documentAccessConditions(input.workspaceId, access)
+      )
+    ).orderBy(asc(schema.documents.indexSequence)).limit(limit + 1)
+  );
+  const hasMore = rows.length > limit;
+  const pageRows = rows.slice(0, limit);
+  const nextSequence = pageRows.at(-1)?.indexSequence ?? afterSequence;
+  if (nextSequence === null) {
+    throw new Error("ready document is missing its index sequence");
+  }
+  return {
+    documents: pageRows.map(mapIndexedDocumentSummary),
+    nextCheckpoint: encodeDocumentIndexCheckpoint({
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      initiatingSubjectId,
+      sequence: nextSequence
+    }),
+    hasMore
+  };
+}
+function encodeDocumentIndexCheckpoint(input) {
+  if (input.sequence < 0n) throw new Error("document index checkpoint sequence is invalid");
+  return Buffer.from(
+    JSON.stringify({
+      v: 1,
+      s: documentIndexCheckpointScope(input),
+      q: input.sequence.toString()
+    }),
+    "utf8"
+  ).toString("base64url");
+}
+function decodeDocumentIndexCheckpoint(value, scope) {
+  try {
+    if (!value || value.length > DOCUMENT_INDEX_CHECKPOINT_MAX_CHARS) {
+      throw new Error("checkpoint length");
+    }
+    const bytes = Buffer.from(value, "base64url");
+    if (bytes.toString("base64url") !== value) throw new Error("checkpoint 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)) {
+      throw new Error("checkpoint payload");
+    }
+    if (parsed.s !== documentIndexCheckpointScope(scope)) {
+      throw new Error("document index checkpoint belongs to a different workspace or subject");
+    }
+    return BigInt(parsed.q);
+  } catch (error) {
+    if (error instanceof Error && error.message === "document index checkpoint belongs to a different workspace or subject") {
+      throw error;
+    }
+    throw new Error("invalid document index checkpoint", { cause: error });
+  }
+}
+function documentIndexCheckpointScope(input) {
+  return createHash("sha256").update("opengeni:document-index-checkpoint:v1\0").update(input.accountId).update("\0").update(input.workspaceId).update("\0").update(canonicalEffectiveDocumentSubject(input.initiatingSubjectId)).digest("hex");
+}
+function canonicalEffectiveDocumentSubject(value) {
+  const subjectId = cleanString(value);
+  if (!subjectId || subjectId !== value) {
+    throw new Error("effective document retrieval requires an initiating subject");
+  }
+  if (new TextEncoder().encode(subjectId).byteLength > DOCUMENT_AUTHORITY_SUBJECT_MAX_BYTES) {
+    throw new Error(
+      `effective document initiating subject exceeds ${DOCUMENT_AUTHORITY_SUBJECT_MAX_BYTES} UTF-8 bytes`
+    );
+  }
+  return subjectId;
+}
 async function getDocument(db, workspaceId, documentId, access) {
   return await withDocumentRls(db, workspaceId, access, async (scopedDb) => {
     const [row] = await scopedDb.select().from(schema.documents).where(
@@ -1024,6 +1311,293 @@ async function searchEffectiveDocuments(db, input, services = createDocumentServ
     services
   );
 }
+async function searchEffectiveKnowledge(db, input, services = createDocumentServices()) {
+  const initiatingSubjectId = canonicalEffectiveDocumentSubject(input.initiatingSubjectId);
+  const ranked = await searchEffectiveDocuments(
+    db,
+    { ...input, initiatingSubjectId, surface: "agent" },
+    services
+  );
+  if (ranked.length === 0) return { results: [] };
+  const access = { agentOnly: true, viewerSubjectId: initiatingSubjectId };
+  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(
+      and(
+        eq(schema.documents.accountId, input.accountId),
+        eq(schema.documentChunks.accountId, input.accountId),
+        inArray(
+          schema.documentChunks.id,
+          ranked.map((result) => result.chunkId)
+        ),
+        eq(schema.documents.status, "ready"),
+        ...documentAccessConditions(input.workspaceId, access)
+      )
+    )
+  );
+  const currentByChunkId = new Map(current.map((row) => [row.chunk.id, row]));
+  return {
+    results: 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
+          }
+        }
+      ];
+    })
+  };
+}
+async function getEffectiveKnowledgeRecord(db, input) {
+  const initiatingSubjectId = canonicalEffectiveDocumentSubject(input.initiatingSubjectId);
+  const target = parseKnowledgeRecordId(input.id);
+  const access = { agentOnly: true, viewerSubjectId: initiatingSubjectId };
+  return await withDocumentAccountRls(
+    db,
+    input.accountId,
+    input.workspaceId,
+    access,
+    async (scopedDb) => {
+      if (target.kind === "document") {
+        const [document] = await scopedDb.select().from(schema.documents).where(
+          and(
+            eq(schema.documents.accountId, input.accountId),
+            eq(schema.documents.id, target.id),
+            eq(schema.documents.status, "ready"),
+            ...documentAccessConditions(input.workspaceId, access)
+          )
+        ).limit(1);
+        return document ? knowledgeDocumentRecord(document) : 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(
+        and(
+          eq(schema.documents.accountId, input.accountId),
+          eq(schema.documentChunks.accountId, input.accountId),
+          eq(schema.documentChunks.id, target.id),
+          eq(schema.documents.status, "ready"),
+          ...documentAccessConditions(input.workspaceId, access)
+        )
+      ).limit(1);
+      return row ? knowledgeChunkRecord(row.document, row.chunk) : null;
+    }
+  );
+}
+async function browseEffectiveKnowledge(db, input) {
+  const initiatingSubjectId = canonicalEffectiveDocumentSubject(input.initiatingSubjectId);
+  const limit = input.limit ?? 20;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
+    throw new Error("knowledge browse limit must be between 1 and 50");
+  }
+  const topic = input.topic === void 0 ? null : cleanString(input.topic) ?? null;
+  if (input.topic !== void 0 && (!topic || topic !== input.topic || topic.length > 256)) {
+    throw new Error("knowledge browse topic is invalid");
+  }
+  const sourceKinds = [...new Set(input.sourceKinds ?? [])].sort();
+  const parent = input.parentId ? parseKnowledgeRecordId(input.parentId) : null;
+  if (parent?.kind === "document_chunk") {
+    throw new Error("knowledge browse parent must be a document record");
+  }
+  if (parent && (topic || sourceKinds.length > 0)) {
+    throw new Error("knowledge browse document contents do not accept topic/source filters");
+  }
+  const cursorScope = {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    initiatingSubjectId,
+    parentId: parent ? `${parent.kind}:${parent.id}` : null,
+    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 };
+  return await withDocumentAccountRls(
+    db,
+    input.accountId,
+    input.workspaceId,
+    access,
+    async (scopedDb) => {
+      if (parent) {
+        const [authorizedParent] = await scopedDb.select({ id: schema.documents.id }).from(schema.documents).where(
+          and(
+            eq(schema.documents.accountId, input.accountId),
+            eq(schema.documents.id, parent.id),
+            eq(schema.documents.status, "ready"),
+            ...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(
+          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"),
+            ...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
+        };
+      }
+      const conditions = [
+        eq(schema.documents.accountId, input.accountId),
+        eq(schema.documents.status, "ready"),
+        isNotNull(schema.documents.indexSequence),
+        gt(schema.documents.indexSequence, after),
+        ...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 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
+      };
+    }
+  );
+}
+function encodeKnowledgeBrowseCursor(scope, position) {
+  if (position < 0n) throw new Error("knowledge browse cursor position is invalid");
+  return Buffer.from(
+    JSON.stringify({ v: 1, s: knowledgeBrowseCursorScope(scope), q: position.toString() }),
+    "utf8"
+  ).toString("base64url");
+}
+function decodeKnowledgeBrowseCursor(value, scope) {
+  try {
+    if (!value || value.length > KNOWLEDGE_BROWSE_CURSOR_MAX_CHARS) {
+      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(",") !== "q,s,v" || parsed.v !== 1 || 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)) {
+      throw new Error("knowledge browse cursor belongs to a different scope");
+    }
+    const position = BigInt(parsed.q);
+    if (position > 9223372036854775807n) throw new Error("cursor position");
+    return position;
+  } catch (error) {
+    if (error instanceof Error && error.message === "knowledge browse cursor belongs to a different scope") {
+      throw error;
+    }
+    throw new Error("invalid knowledge browse cursor", { cause: error });
+  }
+}
+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");
+}
+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(
+    value
+  );
+  if (!match) throw new Error("invalid knowledge record id");
+  return { kind: match[1], id: match[2].toLowerCase() };
+}
+function knowledgeDocumentRecord(document) {
+  if (!document.indexedAt) throw new Error(`Ready document is missing indexed_at: ${document.id}`);
+  const projected = projectKnowledgeRecord({
+    title: document.title,
+    body: document.summary,
+    summary: document.summary,
+    topics: document.topics,
+    metadata: { parser: document.parser, chunkCount: document.chunkCount },
+    source: knowledgeSource(document)
+  });
+  return {
+    id: `document:${document.id}`,
+    kind: "document",
+    title: projected.title,
+    content: projected.content,
+    authority: { kind: normalizeDocumentAuthorityKind(document.authorityKind) },
+    provenance: {
+      source: projected.source,
+      indexedAt: document.indexedAt.toISOString()
+    },
+    lifecycle: { state: "active", updatedAt: document.updatedAt.toISOString() },
+    quality: knowledgeQuality(document),
+    links: knowledgeSourceLinks(projected.source.uri),
+    projection: projected.projection
+  };
+}
+function knowledgeChunkRecord(document, chunk) {
+  if (!document.indexedAt) throw new Error(`Ready document is missing indexed_at: ${document.id}`);
+  const projected = projectKnowledgeRecord({
+    title: document.title,
+    body: chunk.text,
+    summary: document.summary,
+    topics: document.topics,
+    metadata: { ...chunk.metadata, chunkIndex: chunk.chunkIndex },
+    source: knowledgeSource(document)
+  });
+  return {
+    id: `document_chunk:${chunk.id}`,
+    kind: "document_chunk",
+    title: projected.title,
+    content: projected.content,
+    authority: { kind: normalizeDocumentAuthorityKind(document.authorityKind) },
+    provenance: {
+      source: projected.source,
+      indexedAt: document.indexedAt.toISOString()
+    },
+    lifecycle: { state: "active", updatedAt: document.updatedAt.toISOString() },
+    quality: knowledgeQuality(document),
+    links: [
+      { relation: "parent", target: { kind: "knowledge", id: `document:${document.id}` } },
+      ...knowledgeSourceLinks(projected.source.uri)
+    ],
+    projection: projected.projection
+  };
+}
+function knowledgeSource(document) {
+  return {
+    kind: normalizeKnowledgeSourceKind(document.sourceKind),
+    uri: document.sourceUri,
+    externalId: document.sourceExternalId,
+    title: document.sourceTitle,
+    author: document.sourceAuthor,
+    createdAt: document.sourceCreatedAt?.toISOString() ?? null,
+    updatedAt: document.sourceUpdatedAt?.toISOString() ?? null,
+    version: document.sourceVersion
+  };
+}
+function knowledgeQuality(document) {
+  if (!document.indexedAt) throw new Error(`Ready document is missing indexed_at: ${document.id}`);
+  return {
+    trust: "sourced",
+    freshnessAt: (document.sourceUpdatedAt ?? document.indexedAt).toISOString(),
+    conflict: "not_evaluated",
+    correction: "current_source_version"
+  };
+}
+function knowledgeSourceLinks(sourceUri) {
+  return sourceUri ? [{ relation: "source", target: { kind: "external", uri: sourceUri } }] : [];
+}
 async function vectorSearchDocuments(db, input, limit, services) {
   const queryEmbedding = await services.embedder.embedQuery(input.query);
   validateEmbedding(queryEmbedding, services.embedder.dimensions, services.embedder.model);
@@ -1508,6 +2082,40 @@ function mapDocument(row) {
     updatedAt: row.updatedAt.toISOString()
   };
 }
+function mapIndexedDocumentSummary(row) {
+  if (row.indexSequence === null || row.indexedAt === null) {
+    throw new Error(`Ready document is missing index completion metadata: ${row.id}`);
+  }
+  return {
+    id: row.id,
+    title: row.title,
+    parser: row.parser,
+    chunkCount: row.chunkCount,
+    indexedAt: row.indexedAt.toISOString(),
+    summary: row.summary,
+    topics: cleanStringArray(row.topics),
+    source: {
+      kind: normalizeKnowledgeSourceKind(row.sourceKind),
+      uri: row.sourceUri,
+      externalId: row.sourceExternalId,
+      title: row.sourceTitle,
+      author: row.sourceAuthor,
+      createdAt: row.sourceCreatedAt?.toISOString() ?? null,
+      updatedAt: row.sourceUpdatedAt?.toISOString() ?? null,
+      version: row.sourceVersion
+    },
+    provenance: {
+      ingestionWorkspaceId: row.workspaceId,
+      baseId: row.baseId,
+      fileId: row.fileId,
+      authorityKind: normalizeDocumentAuthorityKind(row.authorityKind),
+      authorityWorkspaceId: row.authorityWorkspaceId,
+      authoritySubjectId: row.authoritySubjectId,
+      createdBy: row.createdBy,
+      createdAt: row.createdAt.toISOString()
+    }
+  };
+}
 function normalizeDocumentAuthorityKind(value) {
   switch (value) {
     case "organization":
@@ -1543,6 +2151,7 @@ export {
   DOCUMENT_AUTHORITY_SUBJECT_MAX_BYTES,
   DOCUMENT_CURATION_AUTO_FILE_CONFIDENCE,
   DOCUMENT_CURATION_MAX_INPUT_CHARS,
+  DOCUMENT_INDEX_CHECKPOINT_MAX_CHARS,
   DeterministicEmbeddingProvider,
   HeuristicCurationProvider,
   LiteParseDocumentParser,
@@ -1550,29 +2159,38 @@ export {
   OpenAIEmbeddingProvider,
   RecursiveTextChunker,
   addDocumentToBase,
+  browseEffectiveKnowledge,
   canViewDocument,
   chunkText,
   createDocumentBase,
   createDocumentServices,
+  decodeDocumentIndexCheckpoint,
+  decodeKnowledgeBrowseCursor,
   deleteDocumentFromBase,
   deterministicEmbedding,
   documentOpenAIEmbeddingConfig,
+  encodeDocumentIndexCheckpoint,
+  encodeKnowledgeBrowseCursor,
   ensureDefaultBase,
   getDocument,
   getDocumentBase,
   getDocumentChunk,
   getDocumentInventory,
+  getEffectiveKnowledgeRecord,
   heuristicCuration,
   indexDocumentNow,
   listDocumentBases,
   listDocumentBasesEnsuringDefault,
   listDocuments,
+  listEffectiveIndexedDocuments,
   moveDocumentToBase,
   parseCurationOutcome,
   parseDocumentBytes,
+  projectKnowledgeRecord,
   queueDocumentForReindex,
   resolveDocumentAuthority,
   searchDocuments,
-  searchEffectiveDocuments
+  searchEffectiveDocuments,
+  searchEffectiveKnowledge
 };
 //# sourceMappingURL=index.js.map