@vertesia/common 1.5.0-dev.20260722.120446Z → 1.5.0-dev.20260804.124748Z

package/src/store/dsl-workflow.ts

@@ -1,34 +1,32 @@
-import type { StringValue } from 'ms';
+import type { z } from 'zod';
+import type {
+    ActivityFetchSpecSchema,
+    DSLActivityOptionsSchema,
+    DSLActivitySpecSchema,
+    DSLActivityStepSchema,
+    DSLRetryPolicySchema,
+    DurationValueSchema,
+} from '../api-schemas/process.js';
+import type {
+    WorkflowDefinitionRefSchema,
+    WorkflowInputFileSchema,
+    WorkflowInputSchema,
+} from '../api-schemas/workflow-runs.js';
 import type { ToolExecutionMetadata } from '../tool-execution.js';
 import type { BaseObject } from './common.js';
 import type { WorkflowExecutionPayload } from './index.js';
 import type { ParentClosePolicyType } from './temporalio.js';
 
-export type DurationValue = StringValue | number;
+export type DurationValue = z.infer<typeof DurationValueSchema>;
 
 /**
  * Discriminator for workflow input type - either object IDs or GCS file URIs
  */
 export type WorkflowInputType = 'objectIds' | 'files';
 
-/**
- * File reference with URL and mimetype
- */
-export interface WorkflowInputFile {
-    url: string;
-    mimetype: string;
-}
+export type WorkflowInputFile = z.infer<typeof WorkflowInputFileSchema>;
 
-/**
- * Discriminated union for workflow inputs.
- * Workflows can accept either a list of object IDs (existing behavior) OR a list of file references (new).
- */
-/**
- * @discriminator inputType
- */
-export type WorkflowInput =
-    | { inputType: 'objectIds'; objectIds: string[] }
-    | { inputType: 'files'; files: WorkflowInputFile[] };
+export type WorkflowInput = z.infer<typeof WorkflowInputSchema>;
 
 /**
  * The payload sent when starting a workflow from the temporal client to the workflow instance.
@@ -41,32 +39,12 @@ export interface DSLWorkflowExecutionPayload extends WorkflowExecutionPayload<Re
     workflow: DSLWorkflowSpec;
 }
 
-/**
- * The payload for a DSL activity options.
- *
- * @see ActivityOptions in @temporalio/common
- */
-export interface DSLActivityOptions {
-    startToCloseTimeout?: DurationValue;
-    heartbeatTimeout?: DurationValue;
-    scheduleToStartTimeout?: DurationValue;
-    scheduleToCloseTimeout?: DurationValue;
-    retry?: DSLRetryPolicy;
-}
+export type DSLActivityOptions = z.infer<typeof DSLActivityOptionsSchema>;
 
-/**
- * The payload for a DSL retry policy.
- *
- * @see RetryPolicy in @temporalio/common
- */
-export interface DSLRetryPolicy {
-    backoffCoefficient?: number;
-    initialInterval?: DurationValue;
-    maximumAttempts?: number;
-    maximumInterval?: DurationValue;
-    nonRetryableErrorTypes?: string[];
-}
+export type DSLRetryPolicy = z.infer<typeof DSLRetryPolicySchema>;
 
+// Temporal accepts Date values internally, while the HTTP schema documents their JSON string form.
+// Keep the execution type truthful at the Temporal boundary instead of pretending HTTP validation revives dates.
 export type WorkflowSearchAttributeValue = string[] | number[] | boolean[] | Date[];
 export type WorkflowSearchAttributes = Record<string, WorkflowSearchAttributeValue>;
 
@@ -82,38 +60,10 @@ export interface DSLActivityExecutionPayload<ParamsT extends object> extends Wor
     activityGroupId?: string;
 }
 
+// The published schema intentionally leaves array items open. This narrower authoring type is an
+// internal DSL convenience, not a claim made by the HTTP validator.
 export type ImportSpec = (string | Record<string, string>)[];
-export interface ActivityFetchSpec {
-    /**
-     * The data provider name
-     */
-    type: 'document' | 'document_type' | 'interaction_run';
-    /**
-     * An optional URI to the data source.
-     */
-    source?: string;
-    /**
-     * The query to be executed by the data provider
-     */
-    query: Record<string, unknown>;
-    /**
-     * a string of space separated field names.
-     * Prefix a field name with "-" to exclude it from the result.
-     */
-    select?: string;
-
-    /**
-     * The number of results to return. If the result is limited to 1 the result will be a single object
-     */
-    limit?: number;
-
-    /**
-     * How to handle not found objects.
-     * 1. ignore - Ignore and return an empty array for multi objects query (or undefined for single object query) or empty array for multiple objects throw an error.
-     * 2. throw - Throw an error if the object or no objects are found.
-     */
-    on_not_found?: 'ignore' | 'throw';
-}
+export type ActivityFetchSpec = z.infer<typeof ActivityFetchSpecSchema>;
 
 export interface DSLWorkflowStepBase {
     /**
@@ -123,86 +73,27 @@ export interface DSLWorkflowStepBase {
     type: 'activity' | 'workflow';
 }
 
-export interface DSLActivitySpec<PARAMS extends object = Record<string, unknown>> {
-    /**
-     * The name of the activity function
-     */
-    name: string;
-    /**
-     * Title of the activity to be displayed in the UI workflow builder
-     */
-    title?: string;
-    /**
-     * The description of the activity to e displayed in the UI workflow builder
-     */
-    description?: string;
-    /**
-     * Activities parameters. These parameters can be either literals
-     * (hardcoded strings, numbers, booleans, objects, arrays etc.), either
-     * references to the workflow variables.
-     * The workflow variables are built from the workflow params (e.g. the workflow configuration)
-     * and from the result of the previous activities.
-     */
-    params?: PARAMS;
-    /**
-     * The name of the workflow variable that will store the result of the activity
-     * If not specified the result will not be stored
-     * The parameters describe how the actual parameters will be obtained from the workflow execution vars.
-     * since it may contain references to workflow execution vars.
-     */
-    output?: string;
-
-    /**
-     * A JSON expression which evaluate to true or false similar to mongo matches.
-     * We support for now basic expression like: $true, $false, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $regexp
-     * {$eq: {name: value}},
-     * Ex: {$eq: {wfVarName: value}}
-     */
-    condition?: Record<string, unknown>;
+type DSLActivitySpecWire = z.infer<typeof DSLActivitySpecSchema>;
 
-    /**
-     * The import spec is used to import data from workflow variables.
-     * The import spec is a list of variable names to import from the workflow context.
-     * You can also use objects to rename the imported variables, or to reference an expression.
-     * Example:
-     * ["runId", {"typeId": "docType.id"}]
-     */
+/** The published activity shape with a caller-specializable parameter bag. */
+export type DSLActivitySpec<PARAMS extends object = Record<string, unknown>> = Omit<
+    DSLActivitySpecWire,
+    'params' | 'import'
+> & {
+    params?: PARAMS;
     import?: ImportSpec;
+};
 
-    /**
-     * The fetch phase is used to fetch data from external sources.
-     */
-    fetch?: Record<string, ActivityFetchSpec>;
-
-    /**
-     * Projection to apply to the result. Not all activities support this.
-     */
-    projection?: never | Record<string, unknown>;
-
-    // ---------- Optional features not implemented in a first step ------------
-    /**
-     * If true the activity will be executed in parallel with the other activities.
-     * (i.e. the workflow will not wait for the activity to finish before starting the next one)
-     */
-    parallel?: boolean;
-
-    /**
-     * Await for a parallel activity execution to return.
-     */
-    await?: string; //the activity name to await
+type DSLActivityStepWire = z.infer<typeof DSLActivityStepSchema>;
 
-    /**
-     * Activity options for configuring the activity execution, which overrides the activity options
-     * defined at workflow level.
-     */
-    options?: DSLActivityOptions;
-}
-
-export interface DSLActivityStep<PARAMS extends object = Record<string, unknown>>
-    extends DSLActivitySpec<PARAMS>,
-        DSLWorkflowStepBase {
-    type: 'activity';
-}
+/** The published activity-step shape with a caller-specializable parameter bag. */
+export type DSLActivityStep<PARAMS extends object = Record<string, unknown>> = Omit<
+    DSLActivityStepWire,
+    'params' | 'import'
+> & {
+    params?: PARAMS;
+    import?: ImportSpec;
+};
 
 export interface DSLChildWorkflowStep extends DSLWorkflowStepBase {
     type: 'workflow';
@@ -310,6 +201,26 @@ export interface DSLWorkflowSpecWithActivities extends DSLWorkflowSpecBase {
  */
 export type DSLWorkflowSpec = DSLWorkflowSpecWithSteps | DSLWorkflowSpecWithActivities;
 
+/**
+ * Legacy upsert fields the workflow-definition write endpoints still accept alongside a spec.
+ *
+ * A body carrying `id` updates that definition instead of creating one, with `updated_at` checked
+ * against the stored value for optimistic concurrency. All server-assigned on the read side, hence
+ * optional here and absent from {@link DSLWorkflowSpec}.
+ */
+export interface LegacyWorkflowDefinitionUpsertFields {
+    id?: string;
+    created_at?: string;
+    updated_at?: string;
+}
+
+export type WorkflowDefinitionPayloadWithSteps = DSLWorkflowSpecWithSteps & LegacyWorkflowDefinitionUpsertFields;
+export type WorkflowDefinitionPayloadWithActivities = DSLWorkflowSpecWithActivities &
+    LegacyWorkflowDefinitionUpsertFields;
+
+/** The request body of `POST /workflows/definitions` and `PUT /workflows/definitions/:id`. */
+export type WorkflowDefinitionPayload = WorkflowDefinitionPayloadWithSteps | WorkflowDefinitionPayloadWithActivities;
+
 export function withDSLWorkflowSpecDiscriminator(spec: DSLWorkflowSpecBase): DSLWorkflowSpec {
     if ('steps' in spec && spec.steps) {
         return { ...spec, spec_format: 'steps' } as DSLWorkflowSpecWithSteps;
@@ -328,14 +239,7 @@ export interface DSLWorkflowDefinitionResponse extends DSLWorkflowDefinition {
     spec_format: 'steps' | 'activities';
 }
 
-export interface WorkflowDefinitionRef {
-    id: string;
-    name: string;
-    description?: string;
-    tags?: string[];
-    created_at: Date;
-    updated_at: Date;
-}
+export type WorkflowDefinitionRef = z.infer<typeof WorkflowDefinitionRefSchema>;
 
 export const WorkflowDefinitionRefPopulate = 'id name description tags created_at updated_at';
 

package/src/store/editing-policy-schema.generated.ts

@@ -0,0 +1,30 @@
+// GENERATED FILE — DO NOT EDIT.
+//
+// Written by `scripts/gen-intake-policy-schema.ts` from `ContentTypeEditingPolicySchema` in
+// `../api-schemas/store.ts`, through the same adapter that emits the OpenAPI components. Edit the Zod
+// schema and re-run `pnpm run gen:schemas`; `store.contract.test.ts` fails if this drifts from the
+// canonical component, and fails too if it accepts a value the Zod schema rejects.
+//
+// It exists so the Studio policy editors and the server validators get a self-contained JSON
+// Schema without importing Zod: the package root exports plain data, and `zod` stays out of every
+// browser bundle. The component's `$ref`s are re-rooted from `#/components/schemas/` to `#/$defs/`
+// so AJV and Monaco can compile it standalone.
+//
+// It carries the name consumers have always imported. The Zod object it was emitted from is exported
+// under the same name from `../api-schemas/store.ts`, which the package root does NOT re-export —
+// that split is what keeps zod out of the browser while the alias-provenance gate still sees the
+// `${Name}Schema` convention it requires.
+
+import type { JSONObject } from '../json.js';
+
+export const ContentTypeEditingPolicySchema: JSONObject = {
+    type: 'object',
+    properties: {
+        interaction: {
+            type: 'string',
+            description: 'Agent interaction used for new document-editing sessions. Defaults to sys:GeneralAgent.',
+        },
+    },
+    additionalProperties: false,
+    description: 'Per-content-type policy for collaborative document editing.',
+};

package/src/store/grounded-extraction.ts

@@ -1,4 +1,11 @@
-import type { InteractionExecutionConfiguration } from '../interaction.js';
+import type { z } from 'zod';
+import type {
+    GroundedAssistantResponseSchema,
+    GroundedExtractionRequestSchema,
+    GroundedExtractionResultResponseSchema,
+    GroundedExtractionVerdictSchema,
+    GroundedVerificationBreakdownSchema,
+} from '../api-schemas/document-processing.js';
 import type { WorkflowRunStatus } from './workflow.js';
 
 /**
@@ -7,7 +14,7 @@ import type { WorkflowRunStatus } from './workflow.js';
  * 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';
+export type GroundedExtractionVerdict = z.infer<typeof GroundedExtractionVerdictSchema>;
 
 /**
  * Canonical workflow id for object-scoped grounded extraction. Every entry point
@@ -22,69 +29,7 @@ export function getGroundedExtractionWorkflowId(accountId: string, objectId: str
  * 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;
-}
+export type GroundedExtractionRequest = z.infer<typeof GroundedExtractionRequestSchema>;
 
 /**
  * Response from starting the interactive grounded extraction assistant. The agent
@@ -92,14 +37,7 @@ export interface GroundedExtractionRequest {
  * 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;
-}
+export type GroundedAssistantResponse = z.infer<typeof GroundedAssistantResponseSchema>;
 
 /**
  * Status of a grounded extraction workflow. Carries the doc-level verdict once the
@@ -116,39 +54,10 @@ export interface GroundedExtractionRunStatusResponse extends WorkflowRunStatus {
  * 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;
-}
+export type GroundedVerificationBreakdown = z.infer<typeof GroundedVerificationBreakdownSchema>;
 
 /**
  * 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;
-}
+export type GroundedExtractionResultResponse = z.infer<typeof GroundedExtractionResultResponseSchema>;

package/src/store/index.ts

@@ -6,8 +6,11 @@ export * from './common.js';
 export * from './conversation-state.js';
 export * from './doc-analyzer.js';
 export * from './dsl-workflow.js';
+// The compiled JSON Schema for ContentTypeIntakePolicy, under the name consumers import.
+export * from './editing-policy-schema.generated.js';
 export * from './grounded-extraction.js';
 export * from './hive-memory.js';
+export * from './intake-policy-schema.generated.js';
 export * from './object-types.js';
 export * from './process.js';
 export * from './process-schema.js';