@opengeni/documents 0.5.41 → 0.7.0-canary.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import type { Settings } from "@opengeni/config";
-import { type AddDocumentRequest, CreateDocumentBaseRequest, Document, DocumentAuthorityKind, DocumentBase, DocumentCurationStatus, DocumentSearchMode, DocumentSearchResult, DocumentStatus, DocumentVisibility, FileAsset, KnowledgeBrowseResponse, KnowledgeRecord, KnowledgeSearchResponse, KnowledgeSourceKind, ListIndexedDocumentsResponse } from "@opengeni/contracts";
+import { type AddDocumentRequest, CreateDocumentBaseRequest, Document, DocumentAuthorityKind, DocumentBase, DocumentCurationStatus, DocumentSearchMode, DocumentSearchResult, DocumentStatus, DocumentVisibility, FileAsset, KnowledgeBrowseResponse, KnowledgeRecord, KnowledgeSearchResponse, KnowledgeSourceKind, ListIndexedDocumentsResponse, type ReclassifyDocumentAuthorityRequest, type RunDocumentDefaultCollectionBackfillRequest } from "@opengeni/contracts";
 import { type Database } from "@opengeni/db";
-import type { ObjectStorage } from "@opengeni/storage";
+import { type ObjectStorage } from "@opengeni/storage";
 export { projectKnowledgeRecord } from "./knowledge-projection.js";
 export declare const DEFAULT_DOCUMENT_PARSER = "liteparse";
 export declare const DEFAULT_DOCUMENT_EMBEDDING_MODEL = "text-embedding-3-large";
@@ -84,12 +84,51 @@ export type DocumentAccessFilter = {
      * only when the agent carries the creating subject as its viewer subject.
      */
     agentOnly?: boolean | undefined;
+    /** Exact attempt whose grant snapshot must be revalidated in the content query. */
+    authorizedPersonalAttempt?: {
+        accountId: string;
+        workspaceId: string;
+        sessionId: string;
+        attemptId: string;
+    } | undefined;
 };
 export type DocumentAuthority = {
     kind: DocumentAuthorityKind;
     workspaceId: string | null;
     subjectId: string | null;
 };
+/** JSON-safe projection of the opaque capability minted by the API access layer. */
+export type DocumentAccountAdminAuthorization = Readonly<{
+    authorizationId: string;
+    accountId: string;
+    actorSubjectId: string;
+    permission: "account:admin";
+}>;
+export type ReclassifyDocumentAuthorityInput = ReclassifyDocumentAuthorityRequest & {
+    accountId: string;
+    workspaceId: string;
+    documentId: string;
+    actorSubjectId: string;
+    accountAdminAuthorization: DocumentAccountAdminAuthorization | null;
+};
+export type RunDocumentDefaultCollectionBackfillInput = RunDocumentDefaultCollectionBackfillRequest & {
+    accountId: string;
+    workspaceId: string;
+    actorSubjectId: string;
+    accountAdminAuthorization: DocumentAccountAdminAuthorization;
+};
+export type DocumentMigrationAuditInput = {
+    accountId: string;
+    workspaceId: string;
+    actorSubjectId: string;
+    accountAdminAuthorization: DocumentAccountAdminAuthorization;
+    limit?: number | undefined;
+    cursor?: string | undefined;
+};
+export type AgentDocumentAuthorityContext = {
+    sessionId: string;
+    attemptId: string;
+};
 export type DocumentInventoryStatusCounts = Record<DocumentStatus, number>;
 export type DocumentInventorySourceKindCounts = Record<KnowledgeSourceKind, number>;
 export type DocumentInventoryAuthorityKindCounts = Record<DocumentAuthorityKind, number>;
@@ -135,6 +174,7 @@ export type EffectiveDocumentSearchInput = Omit<DocumentSearchInput, "access"> &
     initiatingSubjectId: string;
     /** Agent retrieval additionally enforces documents.agent_access. */
     surface: "human" | "agent";
+    agentAuthority?: AgentDocumentAuthorityContext | undefined;
 };
 export type ListEffectiveIndexedDocumentsInput = {
     accountId: string;
@@ -143,18 +183,22 @@ export type ListEffectiveIndexedDocumentsInput = {
     initiatingSubjectId: string;
     checkpoint?: string | undefined;
     limit?: number | undefined;
+    agentAuthority?: AgentDocumentAuthorityContext | undefined;
 };
 export type EffectiveKnowledgeBrowseInput = {
     accountId: string;
     workspaceId: string;
     /** Immutable human subject accepted for the logical request/turn. */
     initiatingSubjectId: string;
+    /** Human inspection bypasses agent_access but still uses exact subject/RLS authority. */
+    surface?: "human" | "agent" | undefined;
     /** Omit to browse top-level documents; pass a document record id for chunks. */
     parentId?: string | undefined;
     topic?: string | undefined;
     sourceKinds?: KnowledgeSourceKind[] | undefined;
     cursor?: string | undefined;
     limit?: number | undefined;
+    agentAuthority?: AgentDocumentAuthorityContext | undefined;
 };
 export type DocumentIndexHooks = {
     beforeEmbed?: (input: {
@@ -275,6 +319,142 @@ export declare function listDocumentBasesEnsuringDefault(db: Database, input: {
     accountId: string;
     workspaceId: string;
 }): Promise<DocumentBase[]>;
+export declare function runDocumentDefaultCollectionBackfill(db: Database, input: RunDocumentDefaultCollectionBackfillInput): Promise<{
+    runId: string;
+    operationId: string;
+    status: "completed" | "running";
+    lastWorkspaceId: string | null;
+    processedCount: number;
+    createdCount: number;
+    adoptedCount: number;
+    completedAt: string | null;
+}>;
+export declare function listDocumentDefaultCollectionBackfillRuns(db: Database, input: DocumentMigrationAuditInput): Promise<{
+    runs: {
+        runId: string;
+        status: "completed" | "running";
+        lastWorkspaceId: string | null;
+        processedCount: number;
+        createdCount: number;
+        adoptedCount: number;
+        completedAt: string | null;
+        actorSubjectId: string;
+        startedAt: string;
+        updatedAt: string;
+    }[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}>;
+export declare function getDocumentDefaultCollectionBackfillAudit(db: Database, input: DocumentMigrationAuditInput & {
+    runId: string;
+    operationCursor?: string | undefined;
+    receiptCursor?: string | undefined;
+}): Promise<{
+    run: {
+        runId: string;
+        status: "completed" | "running";
+        lastWorkspaceId: string | null;
+        processedCount: number;
+        createdCount: number;
+        adoptedCount: number;
+        completedAt: string | null;
+        actorSubjectId: string;
+        startedAt: string;
+        updatedAt: string;
+    };
+    operations: {
+        operationId: string;
+        result: {
+            runId: string;
+            operationId: string;
+            status: "completed" | "running";
+            lastWorkspaceId: string | null;
+            processedCount: number;
+            createdCount: number;
+            adoptedCount: number;
+            completedAt: string | null;
+        };
+        createdAt: string;
+    }[];
+    receipts: {
+        workspaceId: string;
+        baseId: string;
+        outcome: "adopted" | "created";
+        createdAt: string;
+    }[];
+    operationsHasMore: boolean;
+    operationsNextCursor: string | null;
+    receiptsHasMore: boolean;
+    receiptsNextCursor: string | null;
+}>;
+export declare function listOrganizationDocumentAuthorityReclassifications(db: Database, input: DocumentMigrationAuditInput): Promise<{
+    receipts: {
+        operationId: string;
+        documentId: string;
+        previousAuthority: {
+            kind: "organization" | "personal" | "workspace";
+            workspaceId: string | null;
+            subjectId: string | null;
+            authorityId: string | null;
+        };
+        authority: {
+            kind: "organization" | "personal" | "workspace";
+            workspaceId: string | null;
+            subjectId: string | null;
+            authorityId: string | null;
+        };
+        createdAt: string;
+        actorSubjectId: string;
+        requestWorkspaceId: string;
+    }[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}>;
+export declare function reclassifyDocumentAuthority(db: Database, input: ReclassifyDocumentAuthorityInput): Promise<{
+    operationId: string;
+    documentId: string;
+    previousAuthority: {
+        kind: "organization" | "personal" | "workspace";
+        workspaceId: string | null;
+        subjectId: string | null;
+        authorityId: string | null;
+    };
+    authority: {
+        kind: "organization" | "personal" | "workspace";
+        workspaceId: string | null;
+        subjectId: string | null;
+        authorityId: string | null;
+    };
+    createdAt: string;
+}>;
+export declare function listDocumentAuthorityReclassifications(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    documentId: string;
+    actorSubjectId: string;
+    limit?: number | undefined;
+    cursor?: string | undefined;
+}): Promise<{
+    receipts: {
+        operationId: string;
+        documentId: string;
+        previousAuthority: {
+            kind: "organization" | "personal" | "workspace";
+            workspaceId: string | null;
+            subjectId: string | null;
+            authorityId: string | null;
+        };
+        authority: {
+            kind: "organization" | "personal" | "workspace";
+            workspaceId: string | null;
+            subjectId: string | null;
+            authorityId: string | null;
+        };
+        createdAt: string;
+    }[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}>;
 export declare function addDocumentToBase(db: Database, input: AddDocumentRequest & {
     accountId: string;
     workspaceId: string;
@@ -308,6 +488,14 @@ export declare function deleteDocumentFromBase(db: Database, input: {
     access?: DocumentAccessFilter | undefined;
 }): Promise<void>;
 export declare function listDocuments(db: Database, workspaceId: string, baseId: string, access?: DocumentAccessFilter): Promise<Document[]>;
+/**
+ * List Documents the human can discover and manage from the requested
+ * workspace. Organization Documents are account-wide, workspace Documents are
+ * local, activated organization-user Documents are portable across the owner's
+ * same-organization workspaces, and legacy personal rows remain anchored to
+ * their ingestion workspace through documentAccessConditions.
+ */
+export declare function listAccessibleDocuments(db: Database, workspaceId: string, access: DocumentAccessFilter): Promise<Document[]>;
 /**
  * List newly ready documents in the same effective scope used by agent
  * retrieval. The opaque checkpoint is bound to the account, requesting
@@ -327,6 +515,17 @@ export declare function decodeDocumentIndexCheckpoint(value: string, scope: {
     initiatingSubjectId: string;
 }): bigint;
 export declare function getDocument(db: Database, workspaceId: string, documentId: string, access?: DocumentAccessFilter): Promise<Document | null>;
+/**
+ * Resolve the immutable source file through Document authority in the requested
+ * workspace. The file remains physically owned by its ingestion workspace;
+ * callers never gain generic access to that workspace's file inventory.
+ */
+export declare function getDocumentOriginalFile(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    documentId: string;
+    access: DocumentAccessFilter;
+}): Promise<FileAsset | null>;
 /**
  * Internal ingestion-only read used after the worker has independently resolved
  * and fenced the immutable document authority tuple. It deliberately does not
@@ -338,6 +537,14 @@ export declare function getDocumentForIndexing(db: Database, workspaceId: string
 export declare function queueDocumentForReindex(db: Database, workspaceId: string, documentId: string, access?: DocumentAccessFilter, organizationAuthorityGranted?: boolean): Promise<Document>;
 export declare function indexDocumentNow(db: Database, objectStorage: ObjectStorage, workspaceId: string, documentId: string, services?: DocumentServices, hooks?: DocumentIndexHooks, access?: DocumentAccessFilter): Promise<Document>;
 export declare function searchDocuments(db: Database, input: DocumentSearchInput, services?: Pick<DocumentServices, "embedder">): Promise<DocumentSearchResult[]>;
+export type DocumentCandidateRelevanceFloor = {
+    vectorScore: number;
+    keywordScore: number;
+};
+export declare function selectDocumentSearchCandidateWindow(merged: DocumentSearchResult[], limit: number, relevanceFloor?: DocumentCandidateRelevanceFloor): {
+    results: DocumentSearchResult[];
+    belowRelevanceFloor: number;
+};
 /**
  * Canonical effective retrieval composition for API, SDK, and MCP surfaces.
  * Callers supply the already-authorized immutable initiating subject; no
@@ -351,12 +558,48 @@ export declare function searchEffectiveDocuments(db: Database, input: EffectiveD
  * ranking and response construction disappears rather than leaking stale data.
  */
 export declare function searchEffectiveKnowledge(db: Database, input: EffectiveDocumentSearchInput, services?: Pick<DocumentServices, "embedder">): Promise<KnowledgeSearchResponse>;
+type KnowledgeSearchCandidate = {
+    record: KnowledgeRecord;
+    semanticScore: number;
+    matchType: DocumentSearchMode;
+    vectorScore: number | null;
+    keywordScore: number | null;
+};
+type KnowledgeSearchSelectionInput = {
+    candidates: KnowledgeSearchCandidate[];
+    rankedCandidateCount: number;
+    requestedLimit: number;
+    alreadyBelowRelevanceFloor?: number | undefined;
+    now?: Date | undefined;
+};
+/**
+ * Deterministic, content-safe final selection over already-authorized and
+ * freshly rechecked Knowledge candidates. Exported for boundary tests; callers
+ * must never use it as a substitute for the database authorization pass above.
+ */
+export declare function selectKnowledgeSearchResults(input: KnowledgeSearchSelectionInput): KnowledgeSearchResponse;
+type KnowledgeBrowseEntry = {
+    record: KnowledgeRecord;
+    cursorAfter: string;
+};
+/**
+ * Bound a browse page without skipping records. Tail records omitted for the
+ * response budget remain behind the returned cursor. If one complete record is
+ * itself too large, return a deterministic discovery projection; knowledge_get
+ * remains the freshly authorized full-record path.
+ */
+export declare function selectKnowledgeBrowseRecords(input: {
+    entries: KnowledgeBrowseEntry[];
+    hasMoreAfterEntries: boolean;
+}): KnowledgeBrowseResponse;
 /** Fetch one stable Knowledge record with a fresh authorization check. */
 export declare function getEffectiveKnowledgeRecord(db: Database, input: {
     accountId: string;
     workspaceId: string;
     initiatingSubjectId: string;
+    surface?: "human" | "agent" | undefined;
     id: string;
+    agentAuthority?: AgentDocumentAuthorityContext | undefined;
 }): Promise<KnowledgeRecord | null>;
 /**
  * Browse top-level authorized documents or the chunks of one authorized
@@ -369,6 +612,7 @@ type KnowledgeBrowseCursorScope = {
     workspaceId: string;
     initiatingSubjectId: string;
     parentId: string | null;
+    parentRevision?: string | null | undefined;
     topic: string | null;
     sourceKinds: readonly string[];
 };
@@ -381,17 +625,26 @@ export declare function resolveDocumentAuthority(input: {
     workspaceId: string;
     initiatingSubjectId?: string | null | undefined;
 }): DocumentAuthority;
+export declare function resolveEffectiveDocumentAccess(_db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    initiatingSubjectId: string;
+    surface: "human" | "agent";
+    agentAuthority?: AgentDocumentAuthorityContext | undefined;
+}): Promise<DocumentAccessFilter>;
 /**
  * Whether a single already-fetched document is readable in this workspace.
  *
- * Keep this compatibility predicate as strict as SQL/RLS: personal authority
- * remains anchored to its originating workspace, and unknown or incomplete
- * authority tuples deny instead of falling through as workspace-visible.
+ * Keep this compatibility predicate as strict as SQL/RLS: legacy personal
+ * authority remains origin-workspace anchored while activated personal
+ * authority has a null workspace and follows the exact owner within the org.
  */
 export declare function canViewDocument(document: Pick<DocumentAccessRecord, "authorityKind" | "authoritySubjectId"> & {
     authorityWorkspaceId?: string | null | undefined;
 }, viewerSubjectId: string | null | undefined, workspaceId?: string | null | undefined): boolean;
 type DocumentAccessRecord = {
+    id: string;
+    authorityId: string | null;
     authorityKind: string;
     authorityWorkspaceId: string | null;
     authoritySubjectId: string | null;