@dylanl1/dsh-plugin-pdf 0.1.2 → 0.1.3

package/dist/types/modules/document/page-content.d.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+export declare const PAGE_CONTENT_VERSION = 1;
+export declare const NATIVE_PAGE_CONTENT_EXTRACTION_VERSION = "joined-page-text-v2-native-quality";
+export declare const MAX_PAGE_CONTENT_TEXT = 500000;
+export declare const MAX_PAGE_CONTENT_SPANS = 10000;
+/** All content coordinates use unrotated PDF user space. Missing geometry stays absent. */
+export declare const pageContentRectSchema: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+declare const producerSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    configurationIdentity: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const PageRepresentationSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        "ocr-text": "ocr-text";
+        "image-description": "image-description";
+        "native-text": "native-text";
+    }>;
+    text: z.ZodString;
+    digest: z.ZodString;
+    producer: z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        configurationIdentity: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    inputDigest: z.ZodOptional<z.ZodString>;
+    spans: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        startUtf16: z.ZodNumber;
+        endUtf16: z.ZodNumber;
+        rectPdf: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    }, z.core.$strict>>>;
+    status: z.ZodEnum<{
+        complete: "complete";
+        partial: "partial";
+    }>;
+    warnings: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type PageRepresentation = z.infer<typeof PageRepresentationSchema>;
+export type PageRepresentationProducer = z.infer<typeof producerSchema>;
+export declare const PageContentBlockSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        unknown: "unknown";
+        text: "text";
+        "visual-region": "visual-region";
+        table: "table";
+        formula: "formula";
+    }>;
+    rectPdf: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    nativeRange: z.ZodOptional<z.ZodObject<{
+        startUtf16: z.ZodNumber;
+        endUtf16: z.ZodNumber;
+    }, z.core.$strict>>;
+    representations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            "ocr-text": "ocr-text";
+            "image-description": "image-description";
+            "native-text": "native-text";
+        }>;
+        text: z.ZodString;
+        digest: z.ZodString;
+        producer: z.ZodObject<{
+            id: z.ZodString;
+            version: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            configurationIdentity: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        inputDigest: z.ZodOptional<z.ZodString>;
+        spans: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            startUtf16: z.ZodNumber;
+            endUtf16: z.ZodNumber;
+            rectPdf: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        }, z.core.$strict>>>;
+        status: z.ZodEnum<{
+            complete: "complete";
+            partial: "partial";
+        }>;
+        warnings: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PageContentBlock = z.infer<typeof PageContentBlockSchema>;
+export declare const PageContentSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    sourceDigest: z.ZodString;
+    page: z.ZodNumber;
+    extractionIdentity: z.ZodString;
+    pageRect: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    nativeText: z.ZodObject<{
+        text: z.ZodString;
+        digest: z.ZodString;
+        paragraphBreaks: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>;
+    blocks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            unknown: "unknown";
+            text: "text";
+            "visual-region": "visual-region";
+            table: "table";
+            formula: "formula";
+        }>;
+        rectPdf: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        nativeRange: z.ZodOptional<z.ZodObject<{
+            startUtf16: z.ZodNumber;
+            endUtf16: z.ZodNumber;
+        }, z.core.$strict>>;
+        representations: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                "ocr-text": "ocr-text";
+                "image-description": "image-description";
+                "native-text": "native-text";
+            }>;
+            text: z.ZodString;
+            digest: z.ZodString;
+            producer: z.ZodObject<{
+                id: z.ZodString;
+                version: z.ZodOptional<z.ZodString>;
+                model: z.ZodOptional<z.ZodString>;
+                configurationIdentity: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            inputDigest: z.ZodOptional<z.ZodString>;
+            spans: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                startUtf16: z.ZodNumber;
+                endUtf16: z.ZodNumber;
+                rectPdf: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+            }, z.core.$strict>>>;
+            status: z.ZodEnum<{
+                complete: "complete";
+                partial: "partial";
+            }>;
+            warnings: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    warnings: z.ZodArray<z.ZodString>;
+    failure: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PageContent = z.infer<typeof PageContentSchema>;
+export type PageContentIdentity = Pick<PageContent, 'sourceDigest' | 'page' | 'extractionIdentity'>;
+/** A content digest is independent of document session, evidence and embedding identity. */
+export declare function pageContentDigest(text: string): string;
+/** A caller-owned structural key may name a future detected table/figure, without pretending it is evidence. */
+export declare function pageContentBlockId(page: PageContentIdentity, structuralKey: string): string;
+type RepresentationInput = Omit<PageRepresentation, 'id' | 'digest'>;
+/** Provenance and input pixels participate in identity even when two engines emit identical text. */
+export declare function pageRepresentationId(input: RepresentationInput): string;
+export declare function createPageRepresentation(input: RepresentationInput): PageRepresentation;
+/** Immutable upsert. Every new snapshot crosses the same boundary as a persisted cache record. */
+export declare function appendPageRepresentation(page: PageContent, blockId: string, representation: PageRepresentation): PageContent;
+/** Derived cache records are disposable; invalid data is a cache miss. */
+export declare function parsePageContent(value: unknown): PageContent | undefined;
+export {};

package/dist/types/modules/engines/cache-identity.d.ts

@@ -0,0 +1,16 @@
+import type { EngineConfiguration, EngineDescriptor, EngineJson } from './types.js';
+/** A plain string attests to persistent identity; scoped metadata cannot attest to reuse after restart. */
+export type BackendCacheIdentity = string | {
+    identity: string;
+    reusable: false;
+} | undefined;
+export interface EngineCacheIdentity {
+    fingerprint: string;
+    /** Runtime registration lifetime, also checked before committing asynchronous derivations. */
+    generation: string;
+    reusable: boolean;
+    backendId: string;
+    backendVersion: string;
+}
+/** The caller supplies its platform hash; this shared SDK keeps no Host runtime dependency. */
+export declare function engineCacheIdentity(descriptor: EngineDescriptor, config: EngineConfiguration, generation: string, sessionId: string, backendIdentity: BackendCacheIdentity, hash: (canonical: string) => string, context?: EngineJson): EngineCacheIdentity;

package/dist/types/modules/engines/catalog.d.ts

@@ -12,7 +12,12 @@ export declare const engineCatalogSchema: z.ZodObject<{
                 disabled: "disabled";
                 local: "local";
                 remote: "remote";
+                service: "service";
             }>;
+            capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                "ocr-text": "ocr-text";
+                "image-description": "image-description";
+            }>>>;
             configurationFields: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 key: z.ZodString;
                 label: z.ZodString;
@@ -33,7 +38,12 @@ export declare const engineCatalogSchema: z.ZodObject<{
                 disabled: "disabled";
                 local: "local";
                 remote: "remote";
+                service: "service";
             }>;
+            capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                "ocr-text": "ocr-text";
+                "image-description": "image-description";
+            }>>>;
             configurationFields: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 key: z.ZodString;
                 label: z.ZodString;
@@ -54,7 +64,12 @@ export declare const engineCatalogSchema: z.ZodObject<{
                 disabled: "disabled";
                 local: "local";
                 remote: "remote";
+                service: "service";
             }>;
+            capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                "ocr-text": "ocr-text";
+                "image-description": "image-description";
+            }>>>;
             configurationFields: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 key: z.ZodString;
                 label: z.ZodString;
@@ -75,7 +90,12 @@ export declare const engineCatalogSchema: z.ZodObject<{
                 disabled: "disabled";
                 local: "local";
                 remote: "remote";
+                service: "service";
             }>;
+            capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                "ocr-text": "ocr-text";
+                "image-description": "image-description";
+            }>>>;
             configurationFields: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 key: z.ZodString;
                 label: z.ZodString;

package/dist/types/modules/engines/directory.d.ts

@@ -12,6 +12,7 @@ export declare class EngineDirectory<T> implements EngineDirectorySource {
     constructor(describe: (implementation: T) => EngineDescriptor);
     register(implementation: T, removed?: () => void): () => void;
     get(id: string): T | undefined;
+    generation(id: string): string | undefined;
     has(id: string): boolean;
     values(): IterableIterator<T>;
     descriptor(id: string): EngineDescriptor | undefined;

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

@@ -3,3 +3,6 @@ export * from './directory.js';
 export * from './catalog.js';
 export * from './task.js';
 export type {} from './context.js';
+export { engineCacheIdentity } from './cache-identity.js';
+export type { BackendCacheIdentity, EngineCacheIdentity } from './cache-identity.js';
+export { canonicalEngineJson } from './serialization.js';

package/dist/types/modules/engines/serialization.d.ts

@@ -0,0 +1,3 @@
+import type { EngineJson } from './types.js';
+/** Canonical configuration serialization is shared by Host identity and browser-safe SDKs. */
+export declare function canonicalEngineJson(value: EngineJson): string;

package/dist/types/modules/engines/types.d.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 export declare const engineKinds: readonly ["ocr", "image", "translation", "embedding"];
 export type EngineKind = typeof engineKinds[number];
+export declare const engineCapabilities: readonly ["ocr-text", "image-description"];
+export type EngineCapability = typeof engineCapabilities[number];
 export type EngineJson = null | boolean | number | string | EngineJson[] | {
     [key: string]: EngineJson;
 };
@@ -21,6 +23,12 @@ export declare const configurationFieldSchema: z.ZodObject<{
     required: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type EngineConfigurationField = z.infer<typeof configurationFieldSchema>;
+export declare const engineExecutionSchema: z.ZodEnum<{
+    disabled: "disabled";
+    local: "local";
+    remote: "remote";
+    service: "service";
+}>;
 export declare const engineDescriptorSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -29,7 +37,12 @@ export declare const engineDescriptorSchema: z.ZodObject<{
         disabled: "disabled";
         local: "local";
         remote: "remote";
+        service: "service";
     }>;
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        "ocr-text": "ocr-text";
+        "image-description": "image-description";
+    }>>>;
     configurationFields: z.ZodOptional<z.ZodArray<z.ZodObject<{
         key: z.ZodString;
         label: z.ZodString;

package/dist/types/modules/evidence/agent-page-image.d.ts

@@ -1,4 +1,5 @@
 import type { OcrOutput } from '../../ocr/types.js';
+import type { StagedImageHooks } from '../ocr/index.js';
 import type { HostWorkspaceSnapshot, WorkingCopyReadPort } from '../working-copy/index.js';
 import { type ImageEvidenceSource } from './provenance.js';
 export interface AgentPageImagePort {
@@ -9,36 +10,14 @@ export interface AgentPageImagePort {
         height: number;
     }>;
 }
+/** Capability reporting uses the same selected execution service as image tools. */
 export interface AgentImageUnderstandingPort {
     availability(sessionId: string, signal: AbortSignal): Promise<{
         status: 'available';
-        kind: 'direct-image' | 'derived-text';
     } | {
         status: 'unavailable';
         reason: string;
     }>;
-    prepare(input: {
-        sessionId: string;
-        image: {
-            data: Uint8Array;
-            mediaType: 'image/png';
-            width: number;
-            height: number;
-        };
-        question: string;
-        signal: AbortSignal;
-    }): Promise<{
-        kind: 'direct-image';
-    } | {
-        kind: 'derived-text';
-        text: string;
-        provenance: {
-            backendId: string;
-            mode: 'ocr-text' | 'image-description';
-            model?: string;
-        };
-        limitations?: string;
-    }>;
 }
 export interface AgentOcrPort {
     selectedDescriptor(): {
@@ -69,7 +48,7 @@ export interface AgentOcrPort {
         width: number;
         height: number;
         languages: readonly string[];
-    }): Promise<string>;
+    }, hooks?: StagedImageHooks): Promise<string>;
 }
 export interface AgentImageAttachmentPort {
     imageLimits: {
@@ -93,10 +72,10 @@ export interface AgentImageAttachmentPort {
     }>;
 }
 export interface AgentImageServices {
-    imageUnderstanding(): AgentImageUnderstandingPort | undefined;
     ocr(): AgentOcrPort | undefined;
     attachments(): AgentImageAttachmentPort | undefined;
     requireVisualModel(signal: AbortSignal): Promise<void>;
+    imageHooks?(snapshot: HostWorkspaceSnapshot, png: Uint8Array): StagedImageHooks;
 }
 export interface RenderedPageValue {
     documentId: string;
@@ -120,6 +99,8 @@ export interface RenderedPageValue {
         };
     };
     imageHandle?: string;
+    imageHandleWarning?: string;
+    deliverImage: boolean;
 }
 export interface DerivedPageValue {
     kind: 'derived-text';
@@ -136,95 +117,11 @@ export interface DerivedPageValue {
     evidenceSource: ImageEvidenceSource;
     source: {
         backendId: string;
+        backendVersion?: string;
         mode: 'ocr-text' | 'image-description';
         model?: string;
     };
     limitations?: string;
 }
-/** Render only after model/backend and attachment preflight; never imply a text model saw a page image. */
-export declare function renderPageForAgent(workspaces: WorkingCopyReadPort, pages: AgentPageImagePort, services: AgentImageServices, sessionId: string, documentId: string, page: number, maxEdge: number | undefined, mode: 'current-model' | 'configured-backend' | undefined, question: string | undefined, signal: AbortSignal): Promise<{
-    evidenceSource: ImageEvidenceSource;
-    text: string;
-    totalChars: number;
-    truncated: boolean;
-    limitations?: string | undefined;
-    kind: "derived-text";
-    documentId: string;
-    path: string;
-    page: number;
-    pageCount: number;
-    revision: number;
-    sourceVersion: string;
-    contentVersion: string;
-    source: {
-        backendId: string;
-        mode: "ocr-text" | "image-description";
-        model?: string;
-    };
-} | {
-    image: {
-        originalDimensions?: {
-            width: number;
-            height: number;
-        } | undefined;
-        name?: string | undefined;
-        attachmentId: string;
-        mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
-        bytes: number;
-        width: number;
-        height: number;
-    };
-    imageHandle?: string | undefined;
-    documentId: string;
-    path: string;
-    page: number;
-    pageCount: number;
-    revision: number;
-    sourceVersion: string;
-    contentVersion: string;
-    evidenceSource: ImageEvidenceSource;
-}>;
-/** OCR is an independent, text-only read; geometry remains in rendered-image pixel space. */
-export declare function ocrPageForAgent(workspaces: WorkingCopyReadPort, pages: AgentPageImagePort, ocr: AgentOcrPort | undefined, sessionId: string, documentId: string, page: number, maxEdge: number | undefined, maxChars: number | undefined, signal: AbortSignal): Promise<{
-    text: string;
-    offset: number;
-    totalChars: number;
-    truncated: boolean;
-    status: string;
-    documentId: string;
-    path: string;
-    page: number;
-    pageCount: number;
-    revision: number;
-    sourceVersion: string;
-    contentVersion: string;
-    source: {
-        kind: string;
-        backendId: string;
-        backendVersion: string;
-    };
-    evidenceSource: ImageEvidenceSource;
-    image: {
-        width: number;
-        height: number;
-    };
-    geometry: {
-        status: string;
-        coordinateSpace: string;
-        positionedParts: number;
-        totalParts: number;
-        pdfCoordinatesAvailable: boolean;
-    };
-    lines: {
-        id: string;
-        text: string;
-        box: {
-            x0: number;
-            y0: number;
-            x1: number;
-            y1: number;
-        } | null;
-    }[];
-    totalLines: number;
-    warnings: string[];
-}>;
+/** Produce one immutable page image; generation is independent of the current model's modalities. */
+export declare function renderPageForAgent(workspaces: WorkingCopyReadPort, pages: AgentPageImagePort, services: AgentImageServices, sessionId: string, documentId: string, page: number, maxEdge: number | undefined, signal: AbortSignal): Promise<RenderedPageValue>;

package/dist/types/modules/evidence/agent-page-read.d.ts

@@ -10,7 +10,32 @@ export interface AgentPageReadPort {
     }>;
 }
 /** Bounded joined-text read; no DSH Context or tool protocol enters this module. */
-export declare function readPageWindow(workspaces: WorkingCopyReadPort, pages: AgentPageReadPort, sessionId: string, documentId: string, page: number, offset: number | undefined, maxChars: number | undefined, signal: AbortSignal): Promise<{
+export declare function readPageWindow(workspaces: WorkingCopyReadPort, pages: AgentPageReadPort, sessionId: string, documentId: string, page: number, offset: number | undefined, maxChars: number | undefined, signal: AbortSignal, references?: EvidenceReferenceStore): Promise<{
+    evidence?: {
+        refId: string;
+        documentId: string;
+        sourcePath: string;
+        sourceDigest: string;
+        sourceVersion: string;
+        contentVersion: string;
+        revision: number;
+        page: number;
+        source: "pdf-text";
+        snapshot: {
+            text: string;
+            sha256: string;
+        };
+        locator: {
+            kind: "text-window";
+            startUtf16: number;
+            endUtf16: number;
+            rectsPdf?: number[][] | undefined;
+        };
+        precision: "exact-text" | "approximate-geometry";
+        limitations: string[];
+        extraction?: "local-ocr" | undefined;
+        pageTextDigest?: string | undefined;
+    } | undefined;
     text: string;
     offset: number;
     nextOffset: number | null;
@@ -29,10 +54,13 @@ export declare function readPageWindow(workspaces: WorkingCopyReadPort, pages: A
     sourceDigest: string;
     pageTextDigest: string;
 }>;
-/** Exact/case-sensitive model search, with continuations fenced to one query and PDF version. */
+/** String matching is distinct from ranked retrieval; offsets always refer to the original text. */
 export declare function searchPageWindows(workspaces: WorkingCopyReadPort, pages: AgentPageReadPort, sessionId: string, documentId: string, input: {
     query: string;
+    mode?: 'exact' | 'normalized';
+    page?: number;
     fromPage?: number;
+    maxPages?: number;
     offset?: number;
     cursor?: string;
 }, signal: AbortSignal, references?: EvidenceReferenceStore): Promise<{
@@ -45,9 +73,15 @@ export declare function searchPageWindows(workspaces: WorkingCopyReadPort, pages
     contentVersion: string;
     fromPage: number;
     throughPage: number;
+    mode: "exact" | "normalized";
+    scope: {
+        fromPage: number;
+        throughPage: number;
+    };
     matches: {
         page: number;
         offset: number;
+        endOffset: number;
         excerpt: string;
         evidence?: PdfTextEvidence;
     }[];

package/dist/types/modules/evidence/image-capture.d.ts

@@ -1,9 +1,4 @@
-import type { DerivedPageValue, RenderedPageValue, ocrPageForAgent } from './agent-page-image.js';
+import type { DerivedPageValue, RenderedPageValue } from './agent-page-image.js';
 import type { ImageEvidenceCapture } from './image-reference.js';
-type OcrPageValue = Awaited<ReturnType<typeof ocrPageForAgent>>;
-export type OcrPageEvidenceValue = Pick<OcrPageValue, 'documentId' | 'path' | 'page' | 'revision' | 'sourceVersion' | 'contentVersion' | 'evidenceSource' | 'source' | 'text'>;
 /** Convert a delivered page image or its bounded derivative into metadata-only durable evidence. */
 export declare function captureRenderedPageEvidence(value: RenderedPageValue | DerivedPageValue): ImageEvidenceCapture;
-/** OCR results are text derivatives of rendered pixels, never an image sent to the current model. */
-export declare function captureOcrPageEvidence(value: OcrPageEvidenceValue): ImageEvidenceCapture;
-export {};