@vertesia/common 1.5.0-dev.20260717.131047Z → 1.5.0-dev.20260725.083715Z

package/lib/store/grounded-extraction.d.ts

@@ -0,0 +1,146 @@
+import type { InteractionExecutionConfiguration } from '../interaction.js';
+import type { WorkflowRunStatus } from './workflow.js';
+/**
+ * Document-level trust verdict for a grounded extraction. `good_to_go` means the
+ * extracted content (after any review corrections) can be used without a human
+ * check; `needs_review` means a human should verify it. This reflects content
+ * correctness, not how many citation boxes rendered.
+ */
+export type GroundedExtractionVerdict = 'good_to_go' | 'needs_review';
+/**
+ * Canonical workflow id for object-scoped grounded extraction. Every entry point
+ * must use this id so Temporal prevents overlapping extraction runs per object.
+ */
+export declare function getGroundedExtractionWorkflowId(accountId: string, objectId: string): string;
+/**
+ * Request body to start a grounded extraction on a content object. All fields are
+ * optional: with none set, the object's own content-type schema drives the
+ * extraction with default models and settings.
+ */
+export interface GroundedExtractionRequest {
+    /** JSON schema describing the data to extract. Takes precedence over type_ref. */
+    schema?: Record<string, unknown>;
+    /** Content type id or catalog ref whose object_schema drives the extraction. */
+    type_ref?: string;
+    /** Interaction to use. Defaults to sys:ExtractInformationGrounded. */
+    interaction_name?: string;
+    /** Maximum number of pages to process. */
+    max_pages?: number;
+    /** Run OCR on every page even when a text layer exists. */
+    force_ocr?: boolean;
+    /** Re-run OCR on pages that need it instead of restoring the stored OCR result. */
+    refresh_ocr?: boolean;
+    /** Attach clean page images for layout/semantic context; direct-vision pages also receive checkerboards. */
+    use_vision?: boolean;
+    /**
+     * A1 locate-grid cell size in PDF points for vision pages (drives both the drawn
+     * grid and cell→box resolution). Smaller = finer grid / more cells. Default: 14.
+     */
+    grid_cell_pt?: number;
+    /**
+     * How to read pages that have no digital text layer (scans / image-only pages).
+     * 'vision' (default): read them off the page image with the extraction model,
+     * skipping OCR entirely. 'ocr': legacy path — OCR those pages and block-ground on
+     * the (lossy) OCR text. Set to 'ocr' to revert to the pre-vision behavior.
+     */
+    raster_mode?: 'vision' | 'ocr';
+    /** Maximum pages per extraction call; larger documents are split into sequential windows. */
+    window_pages?: number;
+    /**
+     * Extract with an autonomous agent (views the whole document at once) instead of
+     * the deterministic windowed pipeline. Sidesteps window-boundary splits on long
+     * documents. The workflow stages the artifacts into an agent space, runs a
+     * conversation agent that writes the extraction, then folds it back.
+     */
+    agentic_extraction?: boolean;
+    /** Agent interaction for agentic_extraction. Defaults to sys:GeneralAgent. */
+    extract_agent?: string;
+    /** Update the object's properties with the extracted data. Default: true. */
+    update_properties?: boolean;
+    /** LLM execution configuration (model, environment, ...) for the main pass. */
+    config?: InteractionExecutionConfiguration;
+    /** Execution configuration used instead of `config` on hard content (scans, handwriting). */
+    hard_config?: InteractionExecutionConfiguration;
+    /** Hardness score (0..1) at or above which `hard_config` is used. Default: 0.5. */
+    hardness_threshold?: number;
+    /** Execution configuration for the post-extraction review pass. No review runs when absent. */
+    review_config?: InteractionExecutionConfiguration;
+    /** Hardness score (0..1) at or above which the review runs. Defaults to hardness_threshold. */
+    review_threshold?: number;
+    /** Review triggers when any page's citation coverage falls below this floor. Default: 0.2. */
+    coverage_review_threshold?: number;
+    /** Run the model review even when every citation was digitally verified. Requires review_config. */
+    force_review?: boolean;
+    /**
+     * Free-text operator guidance folded into the extraction prompt to steer a
+     * (re-)extraction, e.g. "part numbers are in the third column; some line items
+     * wrap onto the next row".
+     */
+    operator_instructions?: string;
+    /** Interactive assistant only: the operator's opening message for the assistant conversation. */
+    user_prompt?: string;
+}
+/**
+ * Response from starting the interactive grounded extraction assistant. The agent
+ * run + conversation workflow are launched server-side (recordRun -> stage the
+ * document into the agent space -> launch the interactive conversation); the
+ * client renders the conversation with `agent_run_id`.
+ */
+export interface GroundedAssistantResponse {
+    /** The AgentRun id to stream/render the conversation. */
+    agent_run_id: string;
+    /** The conversation workflow id backing the run. */
+    workflow_id: string;
+    /** The object the assistant is scoped to. */
+    object_id: string;
+}
+/**
+ * Status of a grounded extraction workflow. Carries the doc-level verdict once the
+ * run has completed and written its result.
+ */
+export interface GroundedExtractionRunStatusResponse extends WorkflowRunStatus {
+    /** The trust verdict, present once the run has completed. */
+    verdict?: GroundedExtractionVerdict;
+}
+/**
+ * How each extracted value was verified. Two kinds, both trustworthy:
+ * digitally verified (matched the document's text — digital layer or OCR) and
+ * AI verified (the reviewer confirmed it against the page image — the primary
+ * signal for scanned or handwritten content, which has no text layer to match).
+ */
+export interface GroundedVerificationBreakdown {
+    /** Total number of cited values. */
+    total: number;
+    /** Values matched verbatim against the document's text (digital layer or OCR). */
+    digitally_verified: number;
+    /** Values the reviewer model confirmed against the page image. */
+    ai_verified: number;
+    /** Values read from the image but neither text-matched nor reviewer-confirmed. */
+    unverified: number;
+}
+/**
+ * Completed grounded extraction result: the extracted data with its trust verdict
+ * and verification breakdown, plus a download URL for the full citations artifact.
+ */
+export interface GroundedExtractionResultResponse {
+    object_id: string;
+    /** The extracted data, shaped by the requested schema. */
+    data: Record<string, unknown>;
+    /** Document-level trust verdict. */
+    verdict?: GroundedExtractionVerdict;
+    /** One-sentence rationale for the verdict. */
+    verdict_reason?: string;
+    /** Mean citation confidence in [0,1]. */
+    confidence?: number;
+    /** Per-value verification breakdown. */
+    verification: GroundedVerificationBreakdown;
+    /** Review outcome, when a review pass ran. */
+    review?: {
+        assessment: 'complete' | 'issues_found';
+        summary?: string;
+        corrections_applied?: number;
+    };
+    /** Signed download URL for the full grounded-extraction.json (data + citations + boxes). */
+    result_url?: string | null;
+}
+//# sourceMappingURL=grounded-extraction.d.ts.map

package/lib/store/grounded-extraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounded-extraction.d.ts","sourceRoot":"","sources":["../../src/store/grounded-extraction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,YAAY,GAAG,cAAc,CAAC;AAEtE;;;GAGG;AACH,wBAAgB,+BAA+B,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACtC,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mFAAmF;IACnF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4GAA4G;IAC5G,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC;IAC/B,6FAA6F;IAC7F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,+EAA+E;IAC/E,MAAM,CAAC,EAAE,iCAAiC,CAAC;IAC3C,6FAA6F;IAC7F,WAAW,CAAC,EAAE,iCAAiC,CAAC;IAChD,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,+FAA+F;IAC/F,aAAa,CAAC,EAAE,iCAAiC,CAAC;IAClD,+FAA+F;IAC/F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8FAA8F;IAC9F,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,oGAAoG;IACpG,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iGAAiG;IACjG,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACtC,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,mCAAoC,SAAQ,iBAAiB;IAC1E,6DAA6D;IAC7D,OAAO,CAAC,EAAE,yBAAyB,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC1C,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,oCAAoC;IACpC,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,YAAY,EAAE,6BAA6B,CAAC;IAC5C,8CAA8C;IAC9C,MAAM,CAAC,EAAE;QACL,UAAU,EAAE,UAAU,GAAG,cAAc,CAAC;QACxC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;IACF,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B"}

package/lib/store/grounded-extraction.js

@@ -0,0 +1,8 @@
+/**
+ * Canonical workflow id for object-scoped grounded extraction. Every entry point
+ * must use this id so Temporal prevents overlapping extraction runs per object.
+ */
+export function getGroundedExtractionWorkflowId(accountId, objectId) {
+    return `${accountId.slice(0, 6)}:workflow_execution_request:${objectId}:grounded`;
+}
+//# sourceMappingURL=grounded-extraction.js.map

package/lib/store/grounded-extraction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounded-extraction.js","sourceRoot":"","sources":["../../src/store/grounded-extraction.ts"],"names":[],"mappings":"AAWA;;;GAGG;AACH,MAAM,UAAU,+BAA+B,CAAC,SAAiB,EAAE,QAAgB;IAC/E,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,+BAA+B,QAAQ,WAAW,CAAC;AACtF,CAAC"}

package/lib/store/index.d.ts

@@ -6,6 +6,7 @@ export * from './common.js';
 export * from './conversation-state.js';
 export * from './doc-analyzer.js';
 export * from './dsl-workflow.js';
+export * from './grounded-extraction.js';
 export * from './hive-memory.js';
 export * from './object-types.js';
 export * from './process.js';

package/lib/store/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC"}

package/lib/store/index.js

@@ -6,6 +6,7 @@ export * from './common.js';
 export * from './conversation-state.js';
 export * from './doc-analyzer.js';
 export * from './dsl-workflow.js';
+export * from './grounded-extraction.js';
 export * from './hive-memory.js';
 export * from './object-types.js';
 export * from './process.js';

package/lib/store/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC"}

package/lib/store/store.d.ts

@@ -1,4 +1,6 @@
+import type { JSONSchemaType } from 'ajv';
 import type { ComputedFacetResponse } from '../facets.js';
+import type { InteractionExecutionConfiguration } from '../interaction.js';
 import type { JSONObject } from '../json.js';
 import type { SearchPayload } from '../payload.js';
 import type { SupportedEmbeddingTypes } from '../project.js';
@@ -378,6 +380,12 @@ export interface GenerationRunMetadata {
     date: string;
     model: string;
     target?: string;
+    /**
+     * Fingerprint of the inputs used by property extraction (content etag, type + its object
+     * schema, source, instructions, interaction). Lets a later run skip re-extraction when
+     * nothing changed.
+     */
+    extraction_fingerprint?: string;
 }
 export interface Rendition {
     name: string;
@@ -397,7 +405,86 @@ export interface ContentMetadata {
     location?: Location;
     generation_runs?: GenerationRunMetadata[];
     etag?: string;
+    /** ETag of text materialized from object properties by intake rendering. */
+    rendered_text_etag?: string;
     renditions?: Rendition[];
+    /**
+     * Embedded/technical metadata harvested from the source file by intake
+     * (office docProps, PDF docinfo). Free-form, nature-appropriate keys.
+     */
+    embedded?: Record<string, unknown>;
+    /** Type-detection provenance recorded by the intake sniff pipeline. */
+    type_detection?: TypeDetectionMetadata;
+    /** Locate-pass provenance: which pages the document map found relevant. */
+    locate?: LocateMetadata;
+    /** Vision-evidence provenance for the last visual extraction run. */
+    vision_evidence?: VisionEvidenceMetadata;
+}
+/**
+ * Provenance persisted at `metadata.locate` when the intake locate (document-map) pass runs.
+ * The page list doubles as navigation metadata for the UI.
+ */
+export interface LocateMetadata {
+    /** Relevant pages proposed by the locate pass, in plan-ranked order (1-based). */
+    pages: number[];
+    /** Detail profile the plan requested for visual extraction. */
+    visual_detail?: 'low' | 'standard' | 'high';
+    /** Whether the plan asked for color rendering. */
+    needs_color?: boolean;
+    /** The model's one-line explanation of the selection. */
+    reason?: string;
+    page_count?: number;
+    /** Pages per contact sheet used for the pass (8 or 16). */
+    detail?: number;
+    sheet_count?: number;
+    located_at: string;
+}
+/**
+ * Provenance persisted at `metadata.vision_evidence` whenever intake prepares scoped page
+ * images for visual extraction (design: vision evidence spec — dropped pages are recorded,
+ * never silently batched).
+ */
+export interface VisionEvidenceMetadata {
+    /** Extraction source that requested the evidence. */
+    source_requested?: 'auto' | 'text' | 'vision' | 'mixed';
+    /** Pages rendered and sent as evidence, in ranked order (1-based). */
+    pages_sent: number[];
+    /** Resolved detail profile name. */
+    detail: 'low' | 'standard' | 'high';
+    /** Candidate pages dropped by budget clamping (recorded, not batched). */
+    dropped_pages?: number[];
+    /** The locate plan's reason, when the plan drove the page selection. */
+    plan_reason?: string;
+    /** Which clamps fired (page_count, allowed_details, token budget, page caps, payload). */
+    clamps_applied?: string[];
+    /** Estimated image tokens for the pages sent. */
+    est_tokens?: number;
+    page_count?: number;
+    prepared_at: string;
+}
+/**
+ * Durable provenance persisted at `metadata.type_detection` whenever the intake sniff pipeline
+ * runs. `method` records which mechanism decides the type: the sniff itself (high confidence),
+ * the post-conversion selector (medium/low/other), or the post-conversion selector because the
+ * document was below the small-doc page threshold.
+ */
+export interface TypeDetectionMetadata {
+    method: 'sniff' | 'post_conversion' | 'post_conversion_small_doc';
+    /** Sniffed type id, or 'other'. */
+    type?: string;
+    type_name?: string;
+    /** Sniff confidence, 0..1. */
+    confidence?: number;
+    band?: 'high' | 'medium' | 'low';
+    rationale?: string;
+    alternates?: string[];
+    /** Which evidence kinds the sniff saw. */
+    evidence?: 'text' | 'image' | 'both';
+    page_count?: number;
+    /** Why the sniff LLM call was skipped (e.g. 'below_min_pages'). */
+    skipped_reason?: string;
+    min_pages?: number;
+    detected_at: string;
 }
 export interface TemporalMediaMetadata extends ContentMetadata {
     duration?: number;
@@ -433,9 +520,32 @@ export interface DocumentMetadata extends ContentMetadata {
         image_count?: number;
         zone_count?: number;
         needs_ocr_count?: number;
+        /** Fingerprint of source+policy used for custom conversion, to skip re-converting unchanged docs. */
+        conversion_fingerprint?: string;
     };
+    /**
+     * Grounded-extraction trust signal + key data. Written by the grounded pipeline
+     * (verdict, confidence, citation counts, review status, source etag, ...) and
+     * queryable for list/filter. Open-ended so more grounded key-data can be stored
+     * without a type change.
+     */
+    grounded?: GroundedMetadata;
     sections?: TextSection[];
 }
+/** Grounded-extraction summary stored on document metadata. Additional keys allowed. */
+export interface GroundedMetadata {
+    verdict?: string;
+    confidence?: number;
+    citation_count?: number;
+    verified_citations?: number;
+    reviewed_at?: string;
+    generated_at?: string;
+    /** Source PDF content etag used by the grounded extraction. */
+    source_content_etag?: string | null;
+    /** @deprecated Grounded source identity is tracked by source_content_etag. */
+    source_text_etag?: string | null;
+    [key: string]: unknown;
+}
 export interface Transcript {
     text?: string;
     segments?: TranscriptSegment[];
@@ -569,6 +679,12 @@ interface StoredTypeRef {
      */
     id: string;
     name: string;
+    /**
+     * Display hint from the type's intake policy (`intake.default_view`). Enriched by the
+     * API on single-object reads so clients can pick the initial view without fetching the
+     * type. Absent on list responses and older servers.
+     */
+    default_view?: ContentTypeIntakePolicy['default_view'];
 }
 interface InCodeTypeRef {
     ref_type: 'incode';
@@ -577,6 +693,12 @@ interface InCodeTypeRef {
      */
     id: string;
     name: string;
+    /**
+     * Display hint from the type's intake policy (`intake.default_view`). Enriched by the
+     * API on single-object reads so clients can pick the initial view without fetching the
+     * type. Absent on list responses and older servers.
+     */
+    default_view?: ContentTypeIntakePolicy['default_view'];
 }
 export interface ComplexSearchPayload extends Omit<SearchPayload, 'query'> {
     query?: ComplexSearchQuery;
@@ -601,10 +723,201 @@ export interface ColumnLayout {
      */
     default?: unknown;
 }
+export type ContentObjectTypeStatus = 'active' | 'draft';
+/** Vision detail level names referenced by intake policies. The rendering profiles behind the
+ * names (dpi, max size, quality, color mode) are PLATFORM-defined and project-overridable —
+ * a type only ever references a detail name. */
+export type IntakeVisionDetail = 'low' | 'standard' | 'high';
+/**
+ * Named page scope for intake conversion/extraction: everything or the locate-pass result.
+ * Static page ranges live in the sibling `page_ranges` field (which wins when set) — kept as
+ * a SEPARATE field because scalar-or-collection unions generate unstable API clients.
+ */
+export type IntakePageScope = 'all' | 'located';
+/**
+ * Static page ranges: inclusive [start, end] pairs; negative indexes count from the end of
+ * the document ([[1, 2], [-1, -1]] = first two pages plus the last page).
+ */
+export type IntakePageRanges = [number, number][];
+/** Rendering settings behind a vision detail name (platform defaults, project-overridable
+ * via `configuration.intake.vision_profiles`). */
+export interface IntakeVisionProfileSettings {
+    /** Render resolution in dots per inch. */
+    dpi: number;
+    /** Maximum height/width of the rendered page image in pixels. */
+    max_hw: number;
+    /** JPEG quality (0-100). */
+    quality: number;
+    /** grayscale renders gray always; auto keeps color when the plan asks for it. */
+    color_mode: 'grayscale' | 'auto';
+}
+export interface ContentTypeExtractionGroundingReviewPolicy {
+    /** Set false to disable an inherited grounding review pass for this type. */
+    enabled?: boolean;
+    /** Model execution configuration for the review interaction. */
+    config?: InteractionExecutionConfiguration;
+    /** Hardness score at or above which review runs. Defaults to hardness_threshold. */
+    threshold?: number;
+    /**
+     * Review also runs when any page's citation coverage falls below this
+     * floor (evidence of missed content). Default 0.2.
+     */
+    coverage_threshold?: number;
+    /** Run review regardless of hardness. */
+    force?: boolean;
+}
+export interface ContentTypeExtractionGroundingPolicy {
+    /** Enable PDF block-level citation grounding for property extraction. */
+    enabled?: boolean;
+    /** Grounded extraction interaction. Defaults to the system grounded extractor. */
+    interaction?: string;
+    /** Maximum pages to process. */
+    max_pages?: number;
+    /** Run OCR on every page even when a text layer exists. */
+    force_ocr?: boolean;
+    /** Attach instrumented page images to the grounded extraction prompt. */
+    use_vision?: boolean;
+    /**
+     * How to read pages with no digital text layer (scans / image-only pages).
+     * 'vision' (default): read them off the page image and skip OCR. 'ocr': legacy
+     * path — OCR those pages and block-ground on the (lossy) OCR text.
+     */
+    raster_mode?: 'vision' | 'ocr';
+    /**
+     * A1 locate-grid cell size in PDF points for vision pages. Smaller = finer grid
+     * (more cells, tighter boxes) but can trip weaker models into over-reading;
+     * tune per the model in `config`. Default 15.
+     */
+    grid_cell_pt?: number;
+    /**
+     * Drop block bounding boxes from the extraction prompt. Only sound with
+     * use_vision (layout comes from the image).
+     */
+    omit_block_boxes?: boolean;
+    /** Maximum pages per grounded extraction call before windowing. */
+    window_pages?: number;
+    /** Update object properties with grounded extraction data. Default true. */
+    update_properties?: boolean;
+    /** Model execution configuration for the main grounded extraction interaction. */
+    config?: InteractionExecutionConfiguration;
+    /** Model execution configuration used for hard-to-read content. */
+    hard_config?: InteractionExecutionConfiguration;
+    /** Hardness score at or above which hard_config is used. Default 0.5. */
+    hardness_threshold?: number;
+    /**
+     * Minimum citations-per-leaf-value ratio; completions below it retry with
+     * escalation. Default 0.3.
+     */
+    min_citation_density?: number;
+    /** Re-run OCR instead of restoring durable OCR artifacts (stale pipeline output). */
+    refresh_ocr?: boolean;
+    /** Optional post-extraction review pass. */
+    review?: ContentTypeExtractionGroundingReviewPolicy;
+}
+/**
+ * Per-content-type policy for the standard intake workflows.
+ */
+export interface ContentTypeIntakePolicy {
+    /** Intake orchestration mode for this type. */
+    mode?: 'programmatic' | 'agentic';
+    /** Guidance used when selecting or creating this content type. */
+    identification?: {
+        guidance?: string;
+        distinguish_from?: string;
+        examples?: string[];
+    };
+    /**
+     * Document-map ("locate") pass: page thumbnails tiled into labeled contact sheets, one
+     * vision call returns which pages matter for THIS type. The result can scope conversion
+     * and extraction, and doubles as the vision planner for visual extraction.
+     */
+    locate?: {
+        /** What to look for ("commercial terms, payment schedule, signature pages"). */
+        instructions: string;
+        /** Pages per contact sheet: 8 = bigger tiles (headings readable). Default 16. */
+        detail?: 8 | 16;
+        /** Only run when the page count is at least this. Default 8. */
+        min_pages?: number;
+    };
+    /** Controls source-to-text conversion before extraction and embedding. */
+    text_conversion?: {
+        enabled?: boolean;
+        method?: 'auto' | 'basic' | 'llm' | 'custom';
+        custom?: {
+            interaction?: string;
+            agent?: string;
+        };
+        instructions?: string;
+        output_format?: 'markdown' | 'text';
+        /** Which pages to convert: everything or the locate result. Default all. */
+        scope?: IntakePageScope;
+        /** Static page ranges to convert (wins over `scope` when set). */
+        page_ranges?: IntakePageRanges;
+    };
+    /** Controls schema-property extraction after type assignment. */
+    extraction?: {
+        enabled?: boolean;
+        source?: 'auto' | 'text' | 'vision' | 'mixed';
+        instructions?: string;
+        interaction?: string;
+        /** Which pages extraction sees: everything or the locate result. */
+        scope?: IntakePageScope;
+        /** Static page ranges extraction sees (wins over `scope` when set). */
+        page_ranges?: IntakePageRanges;
+        /** Cap on pages sent to extraction. Default 20. */
+        max_pages?: number;
+        /** Vision evidence budget for visual extraction. Detail names reference platform
+         * profiles; the type never defines dpi/quality/resolution. */
+        vision?: {
+            default_detail?: IntakeVisionDetail;
+            allowed_details?: IntakeVisionDetail[];
+            /** PRIMARY budget: estimated image tokens per extraction call. Default 16000. */
+            max_image_tokens?: number;
+            /** Transport guard in megabytes. Default 16. */
+            max_payload_mb?: number;
+            /** Cap on page images per extraction call. Default 8. */
+            max_pages_per_call?: number;
+        };
+        verification?: {
+            enabled?: boolean;
+            model?: string;
+            environment?: string;
+            materiality?: string;
+            threshold?: number;
+            max_retries?: number;
+            on_fail?: 'flag' | 'block';
+        };
+        /** Controls PDF block-level citation grounding with annotated proof output. */
+        grounding?: ContentTypeExtractionGroundingPolicy;
+    };
+    /** Handlebars template used to materialize extracted properties into object text. */
+    rendering_template?: string;
+    /** Per-type embedding switches. Unspecified values inherit the project policy. */
+    embeddings?: Partial<Record<SupportedEmbeddingTypes, boolean>>;
+    /** Whether intake should generate a table of contents for matching documents. */
+    generate_toc?: boolean;
+    /** Preferred first view for objects of this type. */
+    default_view?: 'auto' | 'text' | 'pdf' | 'image' | 'properties';
+}
+/** Per-content-type policy for collaborative document editing. */
+export interface ContentTypeEditingPolicy {
+    /** Agent interaction used for new document-editing sessions. Defaults to sys:GeneralAgent. */
+    interaction?: string;
+}
+export declare const ContentTypeEditingPolicySchema: JSONSchemaType<ContentTypeEditingPolicy>;
+/** JSON schema for validating ContentTypeIntakePolicy payloads at API/tool boundaries.
+ * NOTE: typed via a cast because AJV's strict `JSONSchemaType` mapping cannot express the
+ * `[number, number]` pair items of `page_ranges` as a uniform-items array. The runtime
+ * schema is compiled (and thus validated) by every consumer and by the schema-acceptance
+ * unit test in packages/workflows. */
+export declare const ContentTypeIntakePolicySchema: JSONSchemaType<ContentTypeIntakePolicy>;
 export interface ContentObjectType extends ContentObjectTypeItem {
 }
 export interface ContentObjectTypeItem extends BaseObject {
+    status?: ContentObjectTypeStatus;
     is_chunkable?: boolean;
+    intake?: ContentTypeIntakePolicy;
+    editing?: ContentTypeEditingPolicy;
     /**
      * This is only included in ContentObjectTypeItem if explicitly requested
      * It is always included in ContentObjectType
@@ -620,7 +933,7 @@ export interface ContentObjectTypeItem extends BaseObject {
      */
     strict_mode?: boolean;
 }
-export type InCodeTypeDefinition = Pick<ContentObjectTypeItem, 'id' | 'name' | 'description' | 'tags' | 'object_schema' | 'table_layout' | 'is_chunkable' | 'strict_mode'>;
+export type InCodeTypeDefinition = Pick<ContentObjectTypeItem, 'id' | 'name' | 'description' | 'tags' | 'object_schema' | 'table_layout' | 'is_chunkable' | 'strict_mode' | 'status' | 'intake' | 'editing'>;
 export interface ContentObjectTypeCatalogEntry extends InCodeTypeDefinition {
     updated_by?: string;
     created_by?: string;