@dylanl1/dsh-plugin-pdf 0.1.2 → 0.1.3

package/dist/types/modules/evidence/index.d.ts

@@ -1,152 +1,25 @@
-import type { HostWorkspaceSnapshot, WorkingCopyReadPort } from '../working-copy/index.js';
-import { type EvidenceReferenceStore, type PdfTextEvidence } from './reference-store.js';
-import type { NativeTextContent } from '../../shared/native.js';
-export { evidenceSha256, imageEvidenceSource } from './provenance.js';
+export { evidenceSha256, imageEvidenceSource, imageEvidenceSourceFromDigests } from './provenance.js';
 export { createTextEvidence, rememberTextEvidence } from './text-evidence.js';
 export { assertFreshSource } from './source-freshness.js';
 export type { FreshSourceRead } from './source-freshness.js';
 export { createTextReferenceResolver } from './text-target.js';
+export { createTextRangeReferences } from './text-range.js';
+export type { TextRangeInput, ReadTextEvidence } from './text-range.js';
 export type { TextReferenceResolverPort, ResolvedTextReference } from './text-target.js';
 export type { ImageEvidenceSource } from './provenance.js';
-export { savedReferenceSchema, savedTextReferenceSchema, savedImageReferenceSchema, textEvidenceSchema, imageEvidenceSchema, createMemoryEvidenceReferenceStore } from './reference-store.js';
-export type { EvidenceReferenceStore, PdfTextEvidence, PdfImageEvidence, SavedReference, SavedTextReference, SavedImageReference } from './reference-store.js';
+export { savedReferenceSchema, savedTextReferenceSchema, savedImageReferenceSchema, savedTextRangeReferenceSchema, textEvidenceSchema, imageEvidenceSchema, createMemoryEvidenceReferenceStore } from './reference-store.js';
+export type { EvidenceReferenceStore, PdfTextEvidence, PdfImageEvidence, SavedReference, SavedTextReference, SavedImageReference, SavedTextRangeReference } from './reference-store.js';
 export { createImageEvidenceRegistry } from './image-reference.js';
 export { prepareTextSelectionEvidence } from './selection.js';
 export type { SelectionEvidenceRequest, SelectionFragment, SelectionTextReader } from './selection.js';
 export type { ImageEvidenceCapture, ImageAttachmentVerifier } from './image-reference.js';
-export { captureRenderedPageEvidence, captureOcrPageEvidence } from './image-capture.js';
-export type { OcrPageEvidenceValue } from './image-capture.js';
-export { windowPageText } from './text-window.js';
+export { captureRenderedPageEvidence } from './image-capture.js';
+export { windowPageText, textWindow } from './text-window.js';
 export { assertToolCursorIdentity, decodeToolCursor, encodeToolCursor } from './tool-cursor.js';
 export { evidenceNavigationRequestSchema, revalidateEvidenceNavigation } from './navigation-check.js';
 export type { EvidenceNavigationRequest } from './navigation-check.js';
 export { readPageWindow, searchPageWindows, listPageAnnotations } from './agent-page-read.js';
 export type { AgentPageReadPort, PageAnnotation } from './agent-page-read.js';
-export { renderPageForAgent, ocrPageForAgent } from './agent-page-image.js';
+export { renderPageForAgent } from './agent-page-image.js';
 export type { AgentPageImagePort, AgentImageServices, AgentOcrPort, AgentImageUnderstandingPort, AgentImageAttachmentPort, RenderedPageValue, DerivedPageValue } from './agent-page-image.js';
-export interface PageTextReadPort {
-    readPageText(sessionId: string, documentId: string, page: number, signal: AbortSignal): Promise<{
-        snapshot: HostWorkspaceSnapshot;
-        content: NativeTextContent;
-    }>;
-}
-/** Session-fenced, read-only evidence use cases. The store is durable in the Host composition. */
-export declare function createEvidenceReader(workspaces: WorkingCopyReadPort, pages: PageTextReadPort, references?: EvidenceReferenceStore): {
-    status: (sessionId: string, documentId: string) => {
-        documentId: string;
-        path: string;
-        pageCount: number;
-        sourceDigest: string;
-        sourceVersion: string;
-        contentVersion: string;
-        revision: number;
-        dirty: boolean;
-        conflict: boolean;
-        canUndo: boolean;
-        canRedo: boolean;
-        observedAt: string;
-        limitations: string[];
-    };
-    locate: (sessionId: string, input: {
-        documentId: string;
-        quote: string;
-        mode?: "exact" | "normalized";
-        page?: number;
-        fromPage?: number;
-        cursor?: string;
-    }, signal: AbortSignal) => Promise<{
-        status: "ok" | "partial" | "ambiguous" | "not_found";
-        documentId: string;
-        path: string;
-        sourceDigest: string;
-        sourceVersion: string;
-        contentVersion: string;
-        revision: number;
-        matches: {
-            page: number;
-            offset: number;
-            endOffset: number;
-            excerpt: string;
-            evidence: PdfTextEvidence;
-        }[];
-        coverage: {
-            pagesScanned: number[];
-            noTextPages: number[];
-            truncated: boolean;
-            nextCursor: string | null;
-        };
-    }>;
-    context: (sessionId: string, input: {
-        documentId: string;
-        focus: {
-            kind: "page-window";
-            page: number;
-            offsetUtf16?: number;
-        } | {
-            kind: "reference";
-            refId: string;
-        } | {
-            kind: "query";
-            quote: string;
-            fromPage?: number;
-        };
-        maxPages?: number;
-        maxChars?: number;
-        cursor?: string;
-    }, signal: AbortSignal) => Promise<{
-        status: "ok" | "partial" | "ambiguous" | "not_found";
-        documentId: string;
-        path: string;
-        sourceDigest: string;
-        sourceVersion: string;
-        contentVersion: string;
-        revision: number;
-        chunks: never[];
-        candidates: {
-            page: number;
-            offset: number;
-            endOffset: number;
-            excerpt: string;
-            evidence: PdfTextEvidence;
-        }[];
-        revalidatedReference: null;
-        coverage: {
-            actualChars: number;
-            actualBytes: number;
-            pagesScanned: number[];
-            noTextPages: number[];
-            truncated: boolean;
-            nextCursor: string | null;
-        };
-        limitations: string[];
-    } | {
-        status: "ok" | "partial" | "no_text";
-        documentId: string;
-        path: string;
-        sourceDigest: string;
-        sourceVersion: string;
-        contentVersion: string;
-        revision: number;
-        chunks: {
-            page: number;
-            evidence: PdfTextEvidence;
-        }[];
-        candidates: never[];
-        revalidatedReference: {
-            from: string;
-            to: string;
-        } | null;
-        limitations: string[];
-        coverage: {
-            pagesScanned: number[];
-            noTextPages: number[];
-            actualChars: number;
-            actualBytes: number;
-            truncated: boolean;
-            nextCursor: string | null;
-        };
-    }>;
-    reference: (sessionId: string, refId: string) => PdfTextEvidence;
-    forgetSession(sessionId: string): Promise<void>;
-    dispose(): void;
-};
+export { observePdfStatus } from './status.js';

package/dist/types/modules/evidence/provenance.d.ts

@@ -18,3 +18,11 @@ export declare function imageEvidenceSource(input: {
     text?: string;
     storedImageSha256?: string;
 }): ImageEvidenceSource;
+/** Staged consumers retain verified digests, never an entire producer PDF snapshot. */
+export declare function imageEvidenceSourceFromDigests(input: {
+    kind: ImageEvidenceSource['kind'];
+    sourceDigest: string;
+    renderedImageSha256: string;
+    text?: string;
+    storedImageSha256?: string;
+}): ImageEvidenceSource;

package/dist/types/modules/evidence/reference-store.d.ts

@@ -162,6 +162,53 @@ export declare const savedTextReferenceSchema: z.ZodObject<{
     createdAt: z.ZodNumber;
 }, z.core.$strict>;
 export type SavedTextReference = z.infer<typeof savedTextReferenceSchema>;
+/** One continuous, bounded passage. Embedded pages keep it valid if child refs are evicted. */
+export declare const savedTextRangeReferenceSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    evidence: z.ZodObject<{
+        refId: z.ZodString;
+        source: z.ZodLiteral<"pdf-text-range">;
+        documentId: z.ZodString;
+        sourcePath: z.ZodString;
+        sourceDigest: z.ZodString;
+        sourceVersion: z.ZodString;
+        contentVersion: z.ZodString;
+        revision: z.ZodNumber;
+        pages: z.ZodArray<z.ZodObject<{
+            evidence: z.ZodObject<{
+                refId: z.ZodString;
+                documentId: z.ZodString;
+                sourcePath: z.ZodString;
+                sourceDigest: z.ZodString;
+                sourceVersion: z.ZodString;
+                contentVersion: z.ZodString;
+                revision: z.ZodNumber;
+                page: z.ZodNumber;
+                source: z.ZodLiteral<"pdf-text">;
+                extraction: z.ZodOptional<z.ZodLiteral<"local-ocr">>;
+                pageTextDigest: z.ZodOptional<z.ZodString>;
+                snapshot: z.ZodObject<{
+                    text: z.ZodString;
+                    sha256: z.ZodString;
+                }, z.core.$strict>;
+                locator: z.ZodObject<{
+                    kind: z.ZodLiteral<"text-window">;
+                    startUtf16: z.ZodNumber;
+                    endUtf16: z.ZodNumber;
+                    rectsPdf: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodNumber>>>;
+                }, z.core.$strict>;
+                precision: z.ZodEnum<{
+                    "exact-text": "exact-text";
+                    "approximate-geometry": "approximate-geometry";
+                }>;
+                limitations: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>;
+            pageTextDigest: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    createdAt: z.ZodNumber;
+}, z.core.$strict>;
+export type SavedTextRangeReference = z.infer<typeof savedTextRangeReferenceSchema>;
 export declare const savedImageReferenceSchema: z.ZodObject<{
     sessionId: z.ZodString;
     evidence: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -397,9 +444,52 @@ export declare const savedReferenceSchema: z.ZodUnion<readonly [z.ZodObject<{
         }>;
     }, z.core.$strict>], "source">;
     createdAt: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    sessionId: z.ZodString;
+    evidence: z.ZodObject<{
+        refId: z.ZodString;
+        source: z.ZodLiteral<"pdf-text-range">;
+        documentId: z.ZodString;
+        sourcePath: z.ZodString;
+        sourceDigest: z.ZodString;
+        sourceVersion: z.ZodString;
+        contentVersion: z.ZodString;
+        revision: z.ZodNumber;
+        pages: z.ZodArray<z.ZodObject<{
+            evidence: z.ZodObject<{
+                refId: z.ZodString;
+                documentId: z.ZodString;
+                sourcePath: z.ZodString;
+                sourceDigest: z.ZodString;
+                sourceVersion: z.ZodString;
+                contentVersion: z.ZodString;
+                revision: z.ZodNumber;
+                page: z.ZodNumber;
+                source: z.ZodLiteral<"pdf-text">;
+                extraction: z.ZodOptional<z.ZodLiteral<"local-ocr">>;
+                pageTextDigest: z.ZodOptional<z.ZodString>;
+                snapshot: z.ZodObject<{
+                    text: z.ZodString;
+                    sha256: z.ZodString;
+                }, z.core.$strict>;
+                locator: z.ZodObject<{
+                    kind: z.ZodLiteral<"text-window">;
+                    startUtf16: z.ZodNumber;
+                    endUtf16: z.ZodNumber;
+                    rectsPdf: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodNumber>>>;
+                }, z.core.$strict>;
+                precision: z.ZodEnum<{
+                    "exact-text": "exact-text";
+                    "approximate-geometry": "approximate-geometry";
+                }>;
+                limitations: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>;
+            pageTextDigest: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    createdAt: z.ZodNumber;
 }, z.core.$strict>]>;
 export type SavedReference = z.infer<typeof savedReferenceSchema>;
-export declare function isSavedTextReference(record: SavedReference): record is SavedTextReference;
 export declare function isSavedImageReference(record: SavedReference): record is SavedImageReference;
 /** Reads are synchronous so a ref may be resolved without trusting a model-supplied path. */
 export interface EvidenceReferenceStore {

package/dist/types/modules/evidence/status.d.ts

@@ -0,0 +1,17 @@
+import type { WorkingCopyReadPort } from '../working-copy/index.js';
+/** Observe an already authorized working copy without acquiring another owner or reading the disk. */
+export declare function observePdfStatus(workspaces: WorkingCopyReadPort, sessionId: string, documentId: string): {
+    documentId: string;
+    path: string;
+    pageCount: number;
+    sourceDigest: string;
+    sourceVersion: string;
+    contentVersion: string;
+    revision: number;
+    dirty: boolean;
+    conflict: boolean;
+    canUndo: boolean;
+    canRedo: boolean;
+    observedAt: string;
+    limitations: string[];
+};

package/dist/types/modules/evidence/text-range.d.ts

@@ -0,0 +1,28 @@
+import type { WorkingCopyReadPort } from '../working-copy/index.js';
+import type { AgentPageReadPort } from './agent-page-read.js';
+import { type EvidenceReferenceStore, type PdfTextEvidence } from './reference-store.js';
+import { type FreshSourceRead } from './source-freshness.js';
+export interface TextRangeInput {
+    start: {
+        page: number;
+        quote: string;
+    };
+    end: {
+        page: number;
+        quote: string;
+    };
+}
+export interface ReadTextEvidence {
+    refId: string;
+    documentId: string;
+    revision: number;
+    contentVersion: string;
+    pages: PdfTextEvidence[];
+    revalidated: boolean;
+}
+/** Pure evidence primitives: read existing evidence or resolve a specifically bounded passage. */
+export declare function createTextRangeReferences(workspaces: WorkingCopyReadPort, pages: AgentPageReadPort, references: EvidenceReferenceStore): {
+    capture: (sessionId: string, documentId: string, range: TextRangeInput, signal: AbortSignal, readSource?: FreshSourceRead) => Promise<ReadTextEvidence>;
+    derive: (sessionId: string, documentId: string, refId: string, quote: string, signal: AbortSignal, readSource?: FreshSourceRead) => Promise<ReadTextEvidence>;
+    readEvidence: (sessionId: string, documentId: string, refId: string, signal: AbortSignal, readSource?: FreshSourceRead) => Promise<ReadTextEvidence>;
+};

package/dist/types/modules/evidence/text-target.d.ts

@@ -22,6 +22,12 @@ export interface ResolvedTextReference {
 }
 export interface TextReferenceResolverPort {
     resolve(sessionId: string, documentId: string, refId: string, signal: AbortSignal, readSource?: FreshSourceRead, quote?: string): Promise<ResolvedTextReference>;
+    resolveRange(sessionId: string, documentId: string, refId: string, signal: AbortSignal, readSource?: FreshSourceRead): Promise<{
+        refId: string;
+        pages: ResolvedTextReference[];
+    }>;
 }
 /** A ref is evidence, not a file-access grant. Reauthorize the live document and all text before use. */
-export declare function createTextReferenceResolver(workspaces: WorkingCopyReadPort, pages: AgentPageReadPort, references: EvidenceReferenceStore): TextReferenceResolverPort;
+export declare function createTextReferenceResolver(workspaces: WorkingCopyReadPort, pages: AgentPageReadPort, references: EvidenceReferenceStore): TextReferenceResolverPort & {
+    resolveRange: NonNullable<TextReferenceResolverPort['resolveRange']>;
+};

package/dist/types/modules/forms/index.d.ts

@@ -7,9 +7,9 @@ export type { FormChoiceGroup, FormChoiceIssue } from './choice-groups.js';
 export type { FormFieldIdentity, FormFieldTarget } from './identity.js';
 export { createFormInspectionRegistry, FormInspectionReferenceError, formControlReferenceSchema, modelFormInspectionFields } from './inspection-references.js';
 export type { FormInspectionRegistry, FormInspectionIdentity, FormControlReference, FormInspectionTarget } from './inspection-references.js';
-export { formValueContract, validateFormChanges, projectedFormValue, FormValidationError } from './validation.js';
-export type { FormValueContract, FormValidationIssue } from './validation.js';
-import { type FormValueContract } from './validation.js';
+export { formValueType, validateFormChanges, projectedFormValue, FormValidationError } from './validation.js';
+export type { FormValueType, FormValidationIssue } from './validation.js';
+import { type FormValueType } from './validation.js';
 export type FormControlMarker = {
     label: string;
     fieldId: string;
@@ -30,7 +30,7 @@ export type FormPageInspection = {
         fieldId: string;
         name: string;
         type: PdfFormField['type'];
-        valueContract: FormValueContract;
+        valueType: FormValueType;
         required: boolean;
         options?: string[];
         maxLength?: number;

package/dist/types/modules/forms/inspection-references.d.ts

@@ -54,6 +54,6 @@ export declare function modelFormInspectionFields(inspection: FormPageInspection
     options?: string[] | undefined;
     sharedFieldKey: string;
     type: "text" | "checkbox" | "radio" | "dropdown" | "option-list" | "unsupported";
-    valueType: "string" | "boolean" | "unsupported" | "string[]";
+    valueType: import("./validation.js").FormValueType;
     required: boolean;
 }[];

package/dist/types/modules/forms/validation.d.ts

@@ -1,12 +1,8 @@
 import { PdfDocumentError, type PdfFormField } from '../../core/pdf-types.js';
 import { type FormFieldTarget } from './identity.js';
-export type FormValueContract = {
-    valueType: 'string' | 'boolean' | 'string[]' | 'unsupported';
-    examples: PdfFormField['value'][];
-    hint: string;
-};
-/** Machine-readable instructions, shared by inspection and validation. Never coerce guessed values. */
-export declare function formValueContract(field: PdfFormField): FormValueContract;
+export type FormValueType = 'string' | 'boolean' | 'string[]' | 'unsupported';
+/** The model receives only the input type; repair hints stay at the validation boundary. */
+export declare function formValueType(field: PdfFormField): FormValueType;
 export type FormIssueCode = 'unknown_field' | 'ambiguous_field' | 'duplicate_field' | 'read_only' | 'unsupported_field_type' | 'field_not_visible' | 'value_type_mismatch' | 'value_too_long' | 'invalid_option' | 'too_many_selections';
 export interface FormValidationIssue {
     index: number;
@@ -16,7 +12,7 @@ export interface FormValidationIssue {
     fieldType?: PdfFormField['type'];
     pages?: number[];
     code: FormIssueCode;
-    expected?: FormValueContract['valueType'];
+    expected?: FormValueType;
     receivedType?: string;
     maxLength?: number;
     hint: string;

package/dist/types/modules/image-understanding/service.d.ts

@@ -1,10 +1,8 @@
-import { type EngineBinding, type EngineConfiguration, type EngineDescriptor } from '../engines/index.js';
+import { type BackendCacheIdentity, type EngineCacheIdentity, type EngineBinding, type EngineConfiguration, type EngineDescriptor } from '../engines/index.js';
 export declare const MAX_IMAGE_BYTES: number;
 export declare const MAX_IMAGE_PIXELS = 24000000;
-export declare const MAX_QUESTION_CHARACTERS = 4096;
+export declare const MAX_IMAGE_PROMPT_CHARACTERS = 4096;
 export declare const MAX_DERIVED_TEXT_CHARACTERS = 32768;
-export type ImageUnderstandingKind = 'direct-image' | 'derived-text';
-export type ImageUnderstandingMode = 'session-vision' | 'ocr-text' | 'image-description';
 export declare class ImageUnderstandingError extends Error {
     readonly code: string;
     constructor(code: string, message: string, options?: ErrorOptions);
@@ -18,60 +16,42 @@ export interface ImageUnderstandingImage {
 export interface ImageUnderstandingRequest {
     sessionId: string;
     image: ImageUnderstandingImage;
-    question: string;
+    prompt: string;
     signal: AbortSignal;
     binding?: EngineBinding;
-    ocrBinding?: EngineBinding;
 }
 export type ImageUnderstandingAvailability = {
     status: 'available';
-    kind: ImageUnderstandingKind;
     backendId: string;
-    limitation?: string;
 } | {
     status: 'unavailable';
     reason: string;
 };
-export type ImageUnderstandingPreparation = {
-    kind: 'direct-image';
-    backendId: string;
-    provenance: {
-        backendId: string;
-        mode: 'session-vision';
-    };
-} | {
-    kind: 'derived-text';
+export interface ImageUnderstandingOutput {
+    text: string;
+    model?: string;
+    limitations?: string;
+}
+export interface ImageUnderstandingResult {
     text: string;
-    provenance: {
+    source: {
         backendId: string;
-        mode: 'ocr-text' | 'image-description';
+        backendVersion: string;
         model?: string;
     };
     limitations?: string;
-};
+}
+/** One execution contract: an image and prompt produce a textual interpretation. */
 export interface ImageUnderstandingBackend {
-    readonly id: string;
-    readonly kind: ImageUnderstandingKind;
-    readonly descriptor?: EngineDescriptor;
-    availability(sessionId: string, signal: AbortSignal, config?: EngineConfiguration, context?: {
-        ocrBinding?: EngineBinding;
-    }): Promise<{
+    readonly descriptor: EngineDescriptor;
+    availability(sessionId: string, signal: AbortSignal, config?: EngineConfiguration): Promise<{
         available: true;
-        limitation?: string;
     } | {
         available: false;
         reason: string;
     }>;
-    prepare(request: ImageUnderstandingRequest, config?: EngineConfiguration): Promise<{
-        kind: 'direct-image';
-        mode: 'session-vision';
-    } | {
-        kind: 'derived-text';
-        text: string;
-        mode: 'ocr-text' | 'image-description';
-        model?: string;
-        limitations?: string;
-    }>;
+    cacheIdentity?(sessionId: string, signal: AbortSignal, config?: EngineConfiguration): Promise<BackendCacheIdentity>;
+    understand(request: ImageUnderstandingRequest, config?: EngineConfiguration): Promise<ImageUnderstandingOutput>;
 }
 /** Selected backend is profile configuration; the caller supplies only Session identity. */
 export declare class HostImageUnderstandingService {
@@ -82,12 +62,14 @@ export declare class HostImageUnderstandingService {
     constructor(selectedBackend: () => string | EngineBinding);
     /** Contributors own the returned disposer through their own Fiber's ctx.effect(). */
     register(backend: ImageUnderstandingBackend): () => void;
-    list(): (EngineDescriptor & {
-        kind: ImageUnderstandingKind;
-    })[];
+    list(): EngineDescriptor[];
     subscribe(listener: () => void): () => void;
     private selection;
-    availability(sessionId: string, signal: AbortSignal, binding?: EngineBinding, ocrBinding?: EngineBinding): Promise<ImageUnderstandingAvailability>;
-    prepare(request: ImageUnderstandingRequest): Promise<ImageUnderstandingPreparation>;
+    selectedDescriptor(binding?: EngineBinding): EngineDescriptor | undefined;
+    availability(sessionId: string, signal: AbortSignal, binding?: EngineBinding): Promise<ImageUnderstandingAvailability>;
+    /** Synchronous fence for consumers retaining an asynchronous identity snapshot. */
+    generation(binding?: EngineBinding): string | undefined;
+    cacheIdentity(sessionId: string, signal: AbortSignal, binding?: EngineBinding): Promise<EngineCacheIdentity>;
+    understand(request: ImageUnderstandingRequest): Promise<ImageUnderstandingResult>;
     dispose(): void;
 }

package/dist/types/modules/model-write/index.d.ts

@@ -31,7 +31,6 @@ export declare const modelAnnotationSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"reference">;
         refId: z.ZodString;
-        quote: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>], "kind">;
     color: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
     comment: z.ZodOptional<z.ZodString>;
@@ -143,8 +142,8 @@ export declare function createModelWriteService(workspaces: ModelWritePort, page
                 page: number;
                 quote: string;
             } | undefined;
-            quote?: string | undefined;
             refId?: string | undefined;
+            quote?: string | undefined;
             page: number;
             rectPdf: import("../../core/pdf-types.js").PdfRect;
         };

package/dist/types/modules/ocr/service.d.ts

@@ -1,4 +1,4 @@
-import { type EngineBinding, type EngineConfiguration } from '../engines/index.js';
+import { type BackendCacheIdentity, type EngineCacheIdentity, type EngineBinding, type EngineConfiguration } from '../engines/index.js';
 import { type OcrAvailability, type OcrEngineDescriptor, type OcrOutput, type OcrRequest } from '../../ocr/types.js';
 /** A Host image request, deliberately independent of PDF documents or page rendering. */
 export interface HostOcrRequest extends OcrRequest {
@@ -11,6 +11,7 @@ export interface HostOcrRequest extends OcrRequest {
 export interface HostOcrBackend {
     readonly descriptor: OcrEngineDescriptor;
     availability(sessionId: string, signal: AbortSignal, config?: EngineConfiguration): Promise<OcrAvailability>;
+    cacheIdentity?(sessionId: string, signal: AbortSignal, config?: EngineConfiguration): Promise<BackendCacheIdentity>;
     recognize(request: HostOcrRequest, config?: EngineConfiguration): Promise<OcrOutput>;
 }
 export interface HostOcrResult extends OcrOutput {
@@ -19,11 +20,50 @@ export interface HostOcrResult extends OcrOutput {
         backendVersion: string;
     };
 }
+/** Producers may bind their own authorization/version checks without coupling OCR to PDFs. */
+export interface StagedImageHooks {
+    /** Producer runtime/session lifetime; propagated into every consumer operation. */
+    signal?: AbortSignal;
+    acquire?(signal: AbortSignal): Promise<() => void>;
+    validate(signal: AbortSignal): Promise<void>;
+    recordDerived?(result: StagedImageDerivative, signal: AbortSignal): Promise<StagedImageEvidence>;
+}
+export interface StagedImageEvidence {
+    refId: string;
+    documentId?: string;
+    page?: number;
+    snapshotChars?: number;
+    truncated?: boolean;
+}
+export interface StagedImageDerivative {
+    text: string;
+    source: {
+        backendId: string;
+        backendVersion?: string;
+        mode: 'ocr-text' | 'image-description';
+        model?: string;
+    };
+    limitations?: string;
+}
+export type StagedImageRequest = Omit<HostOcrRequest, 'signal' | 'timeoutMs'>;
+export type StagedImageRecorder = (result: StagedImageDerivative) => Promise<StagedImageEvidence | undefined>;
+/** An immutable transcript can outlive its input pixels without losing producer authorization. */
+export interface ImageResultGuard {
+    run<T>(sessionId: string, signal: AbortSignal, read: (signal: AbortSignal) => Promise<T>): Promise<T>;
+}
+export interface StagedOcrResult extends HostOcrResult {
+    image: {
+        width: number;
+        height: number;
+    };
+    evidence?: StagedImageEvidence;
+}
 /** The selected backend is application configuration; session identity stays per call. */
 export declare class HostOcrService {
     private readonly selectedBackend;
     private readonly backends;
     private readonly tasks;
+    private readonly imageTasks;
     private readonly staged;
     private readonly expiryTimer;
     private disposed;
@@ -34,11 +74,19 @@ export declare class HostOcrService {
     private selection;
     selectedDescriptor(binding?: EngineBinding): OcrEngineDescriptor | undefined;
     /** Stage bounded image bytes for an agent tool, without exposing a filesystem path or base64 to the model. */
-    stageImage(request: Omit<HostOcrRequest, 'signal' | 'timeoutMs'>): Promise<string>;
+    stageImage(request: StagedImageRequest, hooks?: StagedImageHooks): Promise<string>;
     /** A model may use only an unexpired handle staged for its own Session. */
-    recognizeStaged(handle: string, sessionId: string, signal: AbortSignal): Promise<HostOcrResult>;
+    private stagedImage;
+    /** Capture only owner/lease checks, never the staged request or its image bytes. */
+    imageResultGuard(handle: string, sessionId: string): ImageResultGuard;
+    private withImageOwner;
+    withStagedImage<T>(handle: string, sessionId: string, signal: AbortSignal, consume: (request: StagedImageRequest, record: StagedImageRecorder, signal: AbortSignal) => Promise<T>): Promise<T>;
+    recognizeStaged(handle: string, sessionId: string, signal: AbortSignal): Promise<StagedOcrResult>;
     private pruneStaged;
     availability(sessionId: string, signal?: AbortSignal, binding?: EngineBinding): Promise<OcrAvailability>;
+    /** Synchronous fence for consumers retaining an asynchronous identity snapshot. */
+    generation(binding?: EngineBinding): string | undefined;
+    cacheIdentity(sessionId: string, signal: AbortSignal, binding?: EngineBinding): Promise<EngineCacheIdentity>;
     recognize(request: HostOcrRequest): Promise<HostOcrResult>;
     dispose(): void;
 }