@exellix/exellix-runtime 3.5.1

package/dist/execution-matrix/contracts.d.ts

@@ -0,0 +1,568 @@
+/**
+ * Execution matrix: design-time catalog payload (Catalox) and runtime row (xronox-store).
+ * @see docs/execution-matrix-runtime.md
+ */
+import type { GraphRuntimeObject } from '@exellix/graph-engine';
+/**
+ * Optional per-run knobs merged into `GraphExecutionRequest.runtime`
+ * after the orchestrator supplies `jobId`, `job`, `input`, and seeded `executionMemory`.
+ *
+ * Defined as the optional part of {@link GraphRuntimeObject} minus matrix-owned fields.
+ * It carries run-level options such as `modelConfig`, `aliasConfig`, `nodes`, memory
+ * bags, variables, planning mode, run logs, diagnostics, retries, and per-run hooks.
+ *
+ * Merge precedence and field-level rules: `mergeMatrixGraphExecuteOverrides` in `orchestrator.ts`.
+ * Static graph model data belongs on `GraphModelObject`, not in this override object.
+ */
+export type MatrixGraphExecuteOverrides = Partial<Omit<GraphRuntimeObject, 'jobId' | 'job' | 'input' | 'executionMemory'>>;
+/** Canonical lifecycle for one graph slot on a matrix row. */
+export declare const EXECUTION_MATRIX_STATUSES: readonly ["not-started", "in-progress", "completed", "failed", "skipped"];
+export type ExecutionMatrixStatus = (typeof EXECUTION_MATRIX_STATUSES)[number];
+/**
+ * Eligibility policy for claiming work.
+ *
+ * Drives the host-supplied {@link ClaimNextOptions.fromStatuses} / `extraFilter` defaults,
+ * and (when `ageMinMinutes` / `modelProfileNotIn` are set) joins against
+ * {@link ExecutionMatrixRuntimeStep.lastAttempt}. Convert to claim params with
+ * `eligibilityToClaim(policy, now)` from `src/execution-matrix/eligibility.ts`.
+ */
+export type EligibilityPolicy = {
+    /** Statuses eligible for claim. Default `['not-started']`. */
+    fromStatuses?: ExecutionMatrixStatus[];
+    /** Statuses to never claim even if `fromStatuses` would allow. Default `['in-progress']`. */
+    excludeStatuses?: ExecutionMatrixStatus[];
+    /** Re-claim only when the slot's `lastAttempt.endedAt` is older than this many minutes. */
+    ageMinMinutes?: number;
+    /** Re-claim only when the slot's `lastAttempt.modelProfile` is NOT in this list. */
+    modelProfileNotIn?: string[];
+    /** Free-form extra Mongo-style filter merged into the claim query (e.g. `{ "input.tier": "B" }`). */
+    extraFilter?: Record<string, unknown>;
+};
+/**
+ * Snapshot transform: inline JS source executed in `node:vm` (best-effort isolation, not a security boundary).
+ *
+ * Sandbox surface exposes `records` and `params`; no `require`, no network, no filesystem.
+ */
+export type SnapshotTransform = {
+    language: 'js';
+    source: string;
+    /** Caller-supplied version string used in {@link ExecutionMatrixSnapshotRecord.transformVersion}. */
+    version: string;
+    /** Hard wall-clock cap; default 5_000ms. The catalog parser rejects values above {@link SNAPSHOT_TRANSFORM_TIMEOUT_HARD_CAP_MS}. */
+    timeoutMs?: number;
+    /** Advisory memory cap (best effort; node:vm cannot strictly enforce). */
+    memoryMb?: number;
+};
+/** Hard cap for `transform.timeoutMs` enforced by the catalog parser (5 seconds). */
+export declare const SNAPSHOT_TRANSFORM_TIMEOUT_HARD_CAP_MS = 5000;
+/**
+ * Discriminated union describing how the runtime obtains data for a matrix.
+ *
+ * - `event`: existing API/BFF entry path. The continuous loop is a no-op for this kind;
+ *   the host invokes the runtime when an external event arrives.
+ * - `storage`: bucket / folder / similar; resolver fetches blobs and yields rows.
+ * - `record`: pull rows from a host collection; bundle by `recordsPerRun`.
+ * - `query-snapshot`: pull rows, run a JS transform under `node:vm` to produce one snapshot,
+ *   persist it, and materialize matrix rows from the snapshot.
+ */
+export type DataSource = {
+    kind: 'event';
+    subKind?: 'api' | 'on-demand' | 'chat';
+    correlationKey?: string;
+} | {
+    kind: 'storage';
+    container: string;
+    path?: string;
+    selector?: Record<string, unknown>;
+    pollWhenEmptySeconds?: number;
+    eligibility?: EligibilityPolicy;
+} | {
+    kind: 'record';
+    collectionRef: string;
+    selection?: Record<string, unknown>;
+    /** 1..MAX (catalog parser caps at 1000); default 1. */
+    recordsPerRun?: number;
+    /** Continuous run-mode only; default {@link DEFAULT_RECORD_POLL_SECONDS}. */
+    pollWhenEmptySeconds?: number;
+    eligibility?: EligibilityPolicy;
+} | {
+    kind: 'query-snapshot';
+    collectionRef: string;
+    selection?: Record<string, unknown>;
+    transform: SnapshotTransform;
+    /** `'one-row'` (default) emits one matrix row whose `input.snapshotId` points to the persisted snapshot.
+     *  `'expand'` emits one matrix row per top-level entry in `payload` when payload is an array. */
+    materialize?: 'one-row' | 'expand';
+    /** Continuous run-mode only; default {@link DEFAULT_QUERY_SNAPSHOT_POLL_SECONDS}. */
+    pollWhenEmptySeconds?: number;
+    eligibility?: EligibilityPolicy;
+};
+export type DataSourceKind = DataSource['kind'];
+/** Default empty-poll interval for `record` source kind. */
+export declare const DEFAULT_RECORD_POLL_SECONDS = 60;
+/** Default empty-poll interval for `query-snapshot` source kind. */
+export declare const DEFAULT_QUERY_SNAPSHOT_POLL_SECONDS = 3600;
+/** Default empty-poll interval for `storage` source kind (mirrors record). */
+export declare const DEFAULT_STORAGE_POLL_SECONDS = 60;
+/** Parser cap for `dataSource.recordsPerRun`. */
+export declare const MAX_RECORDS_PER_RUN = 1000;
+/**
+ * How the runtime drives the matrix lifecycle (separate from {@link DataSource}).
+ *
+ * - `continuous`: run-mode loop; pulls from the source until aborted by host `AbortSignal`.
+ * - `single-pass`: on-demand; runs exactly one cycle and returns.
+ *
+ * Default when omitted: `single-pass` (safer; legacy behavior).
+ */
+export type ExecutionMode = {
+    mode: 'continuous';
+} | {
+    mode: 'single-pass';
+};
+export declare const EXECUTION_MODE_VALUES: readonly ["continuous", "single-pass"];
+/** Standardized keys the runtime/loop will read on a runtime row's `input` blob. */
+export declare const RUNTIME_ROW_INPUT_SOURCE_ID_KEY: "sourceId";
+export declare const RUNTIME_ROW_INPUT_SOURCE_IDS_KEY: "sourceIds";
+export declare const RUNTIME_ROW_INPUT_RECORDS_KEY: "records";
+export declare const RUNTIME_ROW_INPUT_SNAPSHOT_ID_KEY: "snapshotId";
+/** Catalox compatibility until first-class catalogType exists (matrix template items). */
+export declare const EXECUTION_MATRIX_CATALOG_TYPE: "execution-matrix";
+/**
+ * Graph catalog items (e.g. `exellix-graphs` native catalog) carry design-time execution policy.
+ * Interim: `metadata.catalogType === "graphs"` (or `kind`) matches {@link GRAPH_CATALOG_METADATA_TYPE}.
+ */
+export declare const GRAPH_CATALOG_METADATA_TYPE: "graphs";
+/** One condition entry on a graph catalog record's execution policy. */
+export type ExecutionMatrixGraphCondition = {
+    conditionId: string;
+    condition: Record<string, unknown>;
+};
+/** Execution policy stored on each graph catalog item (no graphId here — it is the item's graph id). */
+export type ExecutionMatrixGraphExecutionPolicy = {
+    priority: number;
+    conditions?: ExecutionMatrixGraphCondition[];
+    /** Host-defined expression over {@link ExecutionMatrixGraphCondition.conditionId} (e.g. AND/OR/NOT). */
+    conditionRelations?: string;
+};
+/**
+ * One mapped input variant for a graph (host-defined shape; often `selector` / `defaults` / `staticRows`
+ * as in authoring docs).
+ */
+export type ExecutionMatrixMappedInputEntry = Record<string, unknown>;
+/** Design-time graph definition stored as a native catalog item under the graphs catalog. */
+export type ExecutionMatrixGraphCatalogRecord = {
+    graphId: string;
+    mappedInput: ExecutionMatrixMappedInputEntry[];
+    execution: ExecutionMatrixGraphExecutionPolicy;
+};
+/**
+ * Design-time matrix template: work-unit input plus references to graph catalog items, and (optionally)
+ * the typed runtime configuration (data source, execution mode, eligibility) consumed by the run-mode loop.
+ *
+ * Graph ids must exist in the graphs catalog; each referenced item supplies `mappedInput` and `execution.priority`.
+ *
+ * The new fields (`dataSource`, `executionMode`, `eligibility`) are **optional** for backward compat.
+ * Catalogs that omit them keep behaving exactly as before. New CRUD-managed configurations should always
+ * set `dataSource` and `executionMode`; the parser validates them when present.
+ */
+export type ExecutionMatrixCatalogPayload = {
+    input: Record<string, unknown>;
+    /** Non-empty list of `graphId` values referencing items in the graphs catalog (e.g. `exellix-graphs`). */
+    graphs: string[];
+    /** Typed source descriptor; see {@link DataSource}. */
+    dataSource?: DataSource;
+    /** How the runtime drives the loop; see {@link ExecutionMode}. */
+    executionMode?: ExecutionMode;
+    /** Default eligibility for claims; per-call options on claim/batch APIs win on collisions. */
+    eligibility?: EligibilityPolicy;
+};
+/**
+ * Compact metadata about the most recent execution attempt for a slot.
+ *
+ * Persisted by `executeMatrixGraphForClaim` on completion / failure so eligibility filters
+ * such as `ageMinMinutes` and `modelProfileNotIn` can re-claim selectively.
+ */
+export type ExecutionMatrixStepLastAttempt = {
+    /** ISO timestamp at which the run terminated (success or failure). */
+    endedAt?: string;
+    /** Stable key identifying the model/profile used (host-defined; e.g. `'gpt-4o'`). */
+    modelProfile?: string;
+    /** Job correlation id of the attempt. */
+    jobId?: string;
+    /** Final status reached (`'completed'` or `'failed'`); skipped/in-progress are not recorded. */
+    status?: 'completed' | 'failed';
+};
+/** Runtime step aligned with catalog step + execution state. */
+export type ExecutionMatrixRuntimeStep = {
+    graphId: string;
+    priority: number;
+    status: ExecutionMatrixStatus;
+    reason?: unknown;
+    start?: string | null;
+    end?: string | null;
+    lastUpdated: string;
+    /** Optional worker lease tag when claimed. */
+    workerId?: string;
+    /** Caller-supplied job correlation id for this slot’s run (one per execution attempt). */
+    jobId?: string;
+    /** Snapshot of the most recent attempt; used by eligibility filters across re-runs. */
+    lastAttempt?: ExecutionMatrixStepLastAttempt;
+};
+/** Successful graph output row (failures go to failure matrix / collection). */
+export type ExecutionMatrixInference = {
+    graphId: string;
+    knowledge: unknown;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * One materialized input row for a matrix run, persisted in the runtime DB.
+ * Primary key: matrixRowId (xronox primaryKey field name configurable).
+ */
+/**
+ * Slim projection of one graph slot on a runtime row — used for **records eligibility**
+ * rollups (cross-matrix / multi-graph views keyed by source id).
+ *
+ * @see {@link rollupSourceExecutionStatuses}
+ */
+export type ExecutionMatrixStepSummary = {
+    graphId: string;
+    status: ExecutionMatrixStatus;
+    lastAttempt?: ExecutionMatrixStepLastAttempt;
+    matrixRowId: string;
+    matrixCatalogId: string;
+    matrixRunId?: string;
+    /** Parent row {@link ExecutionMatrixRuntimeRecord.updatedAt} (tie-breaking freshness). */
+    rowUpdatedAt: string;
+};
+/**
+ * Map **source key** → **graph id** → latest {@link ExecutionMatrixStepSummary} for that pair.
+ * Built by {@link rollupSourceExecutionStatuses} / {@link ExecutionMatrixRuntime.batchLookupSourceExecutionStatuses}.
+ */
+export type SourceExecutionStatusMap = Record<string, Partial<Record<string, ExecutionMatrixStepSummary>>>;
+/** One matrix scope for {@link ExecutionMatrixRuntime.batchLookupSourceExecutionStatuses}. */
+export type BatchLookupSourceExecutionScope = {
+    matrixCatalogId: string;
+    matrixRunId?: string;
+    /**
+     * When **every** scope lists graph ids, rollups restrict to their union.
+     * If any scope omits this, all graphs on matching rows are included.
+     */
+    graphIds?: string[];
+};
+export type BatchLookupSourceExecutionStatusesOptions = {
+    scopes: BatchLookupSourceExecutionScope[];
+    sourceKeys: string[];
+    /**
+     * Dot-path on {@link ExecutionMatrixRuntimeRecord} for the stable source id.
+     * Default: `input.<{@link RUNTIME_ROW_INPUT_SOURCE_ID_KEY}>`.
+     */
+    sourceKeyPath?: string;
+    /** Max rows read per scope (default `5000`). */
+    limitPerScope?: number;
+    /** Max rows accumulated across scopes (default `50_000`). */
+    globalRowCap?: number;
+};
+/**
+ * **Records graph eligibility** (studio / binding DSL): predicates over rolled-up step summaries.
+ * Distinct from catalog {@link EligibilityPolicy} (“matrix claim eligibility” on one matrix row).
+ */
+export type RecordsEligibilityPolicy = {
+    /** Graph slot the host intends to claim / run next. */
+    targetGraphId: string;
+    /**
+     * Each listed graph must have a status in `allowStatuses`.
+     * Missing graph in the rollup is treated as **`not-started`**.
+     */
+    requireGraphOutcomes?: Array<{
+        graphId: string;
+        allowStatuses: ExecutionMatrixStatus[];
+    }>;
+    /** Minimum minutes since {@link ExecutionMatrixStepLastAttempt.endedAt} for reruns (keyed by graph id). */
+    cooldownMinutesByGraph?: Partial<Record<string, number>>;
+};
+export type RecordsEligibilityResult = {
+    eligible: true;
+} | {
+    eligible: false;
+    reason: string;
+};
+export type ExecutionMatrixRuntimeRecord = {
+    matrixRowId: string;
+    matrixCatalogId: string;
+    /** Catalox native item id of the matrix definition row. */
+    matrixItemId: string;
+    /** Optional batch / run id when the same catalog is executed in waves. */
+    matrixRunId?: string;
+    /**
+     * Stable ordering for claimNext when multiple rows are eligible (lower runs first).
+     * Set by the materializer.
+     */
+    materializationOrder?: number;
+    input: Record<string, unknown>;
+    execution: ExecutionMatrixRuntimeStep[];
+    inferences: ExecutionMatrixInference[];
+    /** ISO timestamps for the row itself. */
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * Optimistic concurrency / lease token for workers when Mongo atomic claim is not used.
+     * Incremented on each successful claim.
+     */
+    claimVersion?: number;
+};
+export type ExecutionMatrixFailureRecord = {
+    failureId: string;
+    matrixRowId: string;
+    matrixCatalogId: string;
+    matrixItemId: string;
+    matrixRunId?: string;
+    graphId: string;
+    /** Same job correlation id passed to graph-engine for this attempt (caller-supplied). */
+    jobId?: string;
+    /** Per-invocation graph run id from graph-engine (`ExecuteGraphResult.taskId` / finalized response). */
+    taskId?: string;
+    reason: unknown;
+    /** Snapshot pointers or small payload for debugging. */
+    inputSnapshot?: Record<string, unknown>;
+    trace?: unknown;
+    runLog?: unknown;
+    errors?: unknown;
+    createdAt: string;
+};
+export type ExecutionMatrixStatusCounts = Record<ExecutionMatrixStatus, number>;
+export type ListMatrixRowsFilter = {
+    matrixCatalogId: string;
+    matrixRunId?: string;
+    /** Filter rows that have this graphId in this status (elemMatch semantics). */
+    graphId?: string;
+    status?: ExecutionMatrixStatus;
+    /** Extra Mongo-style filter merged into query (e.g. { "input.entityId": "x" }). */
+    extraFilter?: Record<string, unknown>;
+};
+export type ListMatrixRowsOptions = ListMatrixRowsFilter & {
+    limit?: number;
+    skip?: number;
+    sort?: Record<string, 1 | -1>;
+};
+/**
+ * Shared dimensions for failure audit queries ({@link ExecutionMatrixRuntime.countFailureRecords},
+ * {@link ExecutionMatrixRuntime.listFailureRecords}, etc.).
+ */
+export type FailureRecordsFilter = {
+    matrixCatalogId: string;
+    matrixRunId?: string;
+    graphId?: string;
+    matrixRowId?: string;
+    /** Inclusive lower bound on `createdAt` (ISO string). */
+    createdAtMin?: string;
+    /** Inclusive upper bound on `createdAt` (ISO string). */
+    createdAtMax?: string;
+};
+/** Filter for counting documents in `exellix_execution_matrix_failures`. */
+export type CountFailureRecordsOptions = FailureRecordsFilter;
+/**
+ * List failures newest-first by default ({@link ExecutionMatrixRuntime.listFailureRecords}
+ * uses `sort: { createdAt: -1 }` when `sort` is omitted).
+ */
+export type ListFailureRecordsOptions = FailureRecordsFilter & {
+    limit?: number;
+    skip?: number;
+    sort?: Record<string, 1 | -1>;
+};
+export type ClaimNextOptions = {
+    matrixCatalogId: string;
+    matrixRunId?: string;
+    graphId: string;
+    /**
+     * Runtime mode: external correlation id for this single graph execution attempt.
+     * When omitted, the orchestrator runs in autonomous mode and generates a jobId from claimed data.
+     */
+    jobId?: string;
+    /**
+     * Runtime-mode sub-option: when true, forward graph-engine `debugMode` on `ExecuteGraphInput`
+     * so the response carries `ExecuteGraphResult.debug.nodes` (per-node trace).
+     * Only valid when `jobId` is provided.
+     */
+    debugMode?: boolean;
+    /** Defaults to only not-started. */
+    fromStatuses?: ExecutionMatrixStatus[];
+    workerId?: string;
+    /** Merged into the claim query (Mongo path or memory filter), e.g. `{ "input.tier": "B" }`. */
+    extraFilter?: Record<string, unknown>;
+    /**
+     * Per-call LLM / traceability overrides forwarded to `executeGraph`.
+     * Shallow-merged over `ProcessMatrixClaimDeps.executeOverrides`; per-call wins on duplicate keys.
+     * @see {@link MatrixGraphExecuteOverrides}
+     */
+    executeOverrides?: MatrixGraphExecuteOverrides;
+};
+export type ClaimRecordOptions = {
+    matrixRowId: string;
+    graphId: string;
+    /** See {@link ClaimNextOptions.jobId}. */
+    jobId?: string;
+    /** See {@link ClaimNextOptions.debugMode}. */
+    debugMode?: boolean;
+    fromStatuses?: ExecutionMatrixStatus[];
+    workerId?: string;
+    /** Merged into the claim query when supported (Mongo). */
+    extraFilter?: Record<string, unknown>;
+    /** See {@link ClaimNextOptions.executeOverrides}. */
+    executeOverrides?: MatrixGraphExecuteOverrides;
+};
+export type ClaimResult = {
+    ok: true;
+    record: ExecutionMatrixRuntimeRecord;
+    graphId: string;
+    /** Index in record.execution for the claimed slot. */
+    stepIndex: number;
+} | {
+    ok: false;
+    reason: 'no_eligible_row' | 'concurrent_claim' | 'row_not_found' | 'claim_paused';
+};
+/** Options for trying graphs in order until one claim succeeds (execute-next / execute-all building block). */
+export type ClaimNextAcrossGraphsOptions = {
+    matrixCatalogId: string;
+    matrixRunId?: string;
+    /** Try these graph ids in order; defaults to all graphs present on matching rows (see runtime). */
+    graphIds?: string[];
+    fromStatuses?: ExecutionMatrixStatus[];
+    workerId?: string;
+    extraFilter?: Record<string, unknown>;
+    /** See {@link ClaimNextOptions.executeOverrides}. Carried through batched runs that delegate here. */
+    executeOverrides?: MatrixGraphExecuteOverrides;
+    /**
+     * When set, invoked before each {@link ExecutionMatrixRuntime.claimNext} attempt (in `graphIds` order).
+     * Return **`false`** to skip this `graphId` without claiming (e.g. graph not published / not operational).
+     */
+    beforeClaimGraph?: (graphId: string) => boolean | Promise<boolean>;
+};
+export type ProcessMatrixGraphBatchOptions = {
+    matrixCatalogId: string;
+    matrixRunId?: string;
+    /** When set, only this graph is considered (same as {@link processNextMatrixClaim}). */
+    graphId?: string;
+    /**
+     * Runtime mode: external correlation id for this single graph execution attempt.
+     * Only valid when this batch is guaranteed to execute at most one graph run (e.g. `limit: 1`).
+     */
+    jobId?: string;
+    /** Runtime-mode sub-option; only valid when `jobId` is provided. See {@link ClaimNextOptions.debugMode}. */
+    debugMode?: boolean;
+    /** Max successful graph runs in this call. Use `1` for "execute next one". Default: unlimited for execute-all. */
+    limit?: number;
+    fromStatuses?: ExecutionMatrixStatus[];
+    workerId?: string;
+    extraFilter?: Record<string, unknown>;
+    /** Safety cap for execute-all loops (default 10_000). */
+    maxIterations?: number;
+    /**
+     * See {@link ClaimNextOptions.executeOverrides}. Applied to every claim in the batch
+     * (each iteration shallow-merges this over `ProcessMatrixClaimDeps.executeOverrides`).
+     */
+    executeOverrides?: MatrixGraphExecuteOverrides;
+};
+/**
+ * Persisted snapshot artifact produced by a `query-snapshot` data source's transform.
+ *
+ * Stored in `exellix_execution_matrix_snapshots` (operational DB). Matrix rows materialized from
+ * a snapshot carry the `snapshotId` on `input` so downstream consumers can re-read the payload.
+ */
+export type ExecutionMatrixSnapshotRecord = {
+    snapshotId: string;
+    matrixCatalogId: string;
+    matrixRunId?: string;
+    /**
+     * Optional Memorix / catalog entity discriminator for dashboards (facet queries, {@link ListSnapshotsOptions.entityType}).
+     * Populate when persisting via {@link buildSnapshotRecord} or your host path.
+     */
+    entityType?: string;
+    /** Stable hash of the source selection + sourceIds used to build the snapshot. */
+    sourceQueryHash: string;
+    /** Source ids that contributed to the snapshot (when known). */
+    sourceIds?: string[];
+    /** Echo of {@link SnapshotTransform.version}. */
+    transformVersion: string;
+    payload: unknown;
+    createdAt: string;
+};
+/** Filter for listing snapshots. */
+export type ListSnapshotsOptions = {
+    matrixCatalogId?: string;
+    matrixRunId?: string;
+    /** Shorthand for `{ entityType }` merged into the read filter. */
+    entityType?: string;
+    /** Merged into the xronox `readMany` filter (same spirit as matrix row `extraFilter`). */
+    extraFilter?: Record<string, unknown>;
+    limit?: number;
+    skip?: number;
+    sort?: Record<string, 1 | -1>;
+};
+/** Filter for {@link ExecutionMatrixRuntime.countSnapshots} (capped read — see runtime JSDoc). */
+export type CountSnapshotsOptions = {
+    matrixCatalogId?: string;
+    matrixRunId?: string;
+    entityType?: string;
+    extraFilter?: Record<string, unknown>;
+};
+/** Persisted matrix execution configuration; primary key `matrixCatalogId`. */
+export type MatrixConfigRecord = {
+    matrixCatalogId: string;
+    /** Optimistic concurrency token; incremented on every successful update. */
+    version: number;
+    payload: ExecutionMatrixCatalogPayload;
+    description?: string;
+    tags?: string[];
+    createdAt: string;
+    updatedAt: string;
+    createdBy?: string;
+    updatedBy?: string;
+};
+/** Publication lifecycle for a graph config row (global per `graphId`, ops DB). */
+export declare const GRAPH_PUBLICATION_STATUSES: readonly ["Draft", "Published", "Archived"];
+export type GraphPublicationStatus = (typeof GRAPH_PUBLICATION_STATUSES)[number];
+/** Whether workers should treat the graph as schedulable (global per `graphId`, ops DB). */
+export declare const GRAPH_OPERATIONAL_STATES: readonly ["NotOperational", "Ready", "Running"];
+export type GraphOperationalState = (typeof GRAPH_OPERATIONAL_STATES)[number];
+/** Persisted graph configuration (mirror of catalog graph items); primary key `graphId`. */
+export type GraphConfigRecord = {
+    graphId: string;
+    version: number;
+    payload: ExecutionMatrixGraphCatalogRecord;
+    /**
+     * Design-time publication gate. Omitted in legacy documents → treated as {@link DEFAULT_GRAPH_PUBLICATION_STATUS}.
+     */
+    publicationStatus?: GraphPublicationStatus;
+    /**
+     * Operational scheduling preference. Omitted in legacy documents → treated as {@link DEFAULT_GRAPH_OPERATIONAL_STATE}.
+     */
+    operationalState?: GraphOperationalState;
+    /** ISO timestamp of the last operational/publication field change (when tracked). */
+    operationalUpdatedAt?: string;
+    operationalUpdatedBy?: string;
+    createdAt: string;
+    updatedAt: string;
+    createdBy?: string;
+    updatedBy?: string;
+};
+/** Default when `publicationStatus` is missing on a persisted graph config (legacy rows). */
+export declare const DEFAULT_GRAPH_PUBLICATION_STATUS: GraphPublicationStatus;
+/** Default when `operationalState` is missing on a persisted graph config (legacy rows). */
+export declare const DEFAULT_GRAPH_OPERATIONAL_STATE: GraphOperationalState;
+/**
+ * Effective merged configuration consumed by the run loop / orchestrator.
+ *
+ * Combines the persisted matrix payload with applied defaults so the loop can dispatch
+ * without re-running default-resolution itself.
+ */
+export type EffectiveMatrixConfig = {
+    matrixCatalogId: string;
+    payload: ExecutionMatrixCatalogPayload;
+    /** Resolved execution mode (defaults to `single-pass`). */
+    executionMode: ExecutionMode;
+    /** Resolved poll-when-empty interval in seconds; only meaningful for kinds the loop drives. */
+    pollWhenEmptySeconds: number;
+    /** Convenience shortcut: `payload.dataSource?.kind` (always present in effective view). */
+    dataSourceKind: DataSourceKind;
+};
+//# sourceMappingURL=contracts.d.ts.map

package/dist/execution-matrix/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/execution-matrix/contracts.ts"],"names":[],"mappings":"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"}

package/dist/execution-matrix/contracts.js

@@ -0,0 +1,44 @@
+/**
+ * Execution matrix: design-time catalog payload (Catalox) and runtime row (xronox-store).
+ * @see docs/execution-matrix-runtime.md
+ */
+/** Canonical lifecycle for one graph slot on a matrix row. */
+export const EXECUTION_MATRIX_STATUSES = [
+    'not-started',
+    'in-progress',
+    'completed',
+    'failed',
+    'skipped',
+];
+/** Hard cap for `transform.timeoutMs` enforced by the catalog parser (5 seconds). */
+export const SNAPSHOT_TRANSFORM_TIMEOUT_HARD_CAP_MS = 5_000;
+/** Default empty-poll interval for `record` source kind. */
+export const DEFAULT_RECORD_POLL_SECONDS = 60;
+/** Default empty-poll interval for `query-snapshot` source kind. */
+export const DEFAULT_QUERY_SNAPSHOT_POLL_SECONDS = 3600;
+/** Default empty-poll interval for `storage` source kind (mirrors record). */
+export const DEFAULT_STORAGE_POLL_SECONDS = DEFAULT_RECORD_POLL_SECONDS;
+/** Parser cap for `dataSource.recordsPerRun`. */
+export const MAX_RECORDS_PER_RUN = 1000;
+export const EXECUTION_MODE_VALUES = ['continuous', 'single-pass'];
+/** Standardized keys the runtime/loop will read on a runtime row's `input` blob. */
+export const RUNTIME_ROW_INPUT_SOURCE_ID_KEY = 'sourceId';
+export const RUNTIME_ROW_INPUT_SOURCE_IDS_KEY = 'sourceIds';
+export const RUNTIME_ROW_INPUT_RECORDS_KEY = 'records';
+export const RUNTIME_ROW_INPUT_SNAPSHOT_ID_KEY = 'snapshotId';
+/** Catalox compatibility until first-class catalogType exists (matrix template items). */
+export const EXECUTION_MATRIX_CATALOG_TYPE = 'execution-matrix';
+/**
+ * Graph catalog items (e.g. `exellix-graphs` native catalog) carry design-time execution policy.
+ * Interim: `metadata.catalogType === "graphs"` (or `kind`) matches {@link GRAPH_CATALOG_METADATA_TYPE}.
+ */
+export const GRAPH_CATALOG_METADATA_TYPE = 'graphs';
+/** Publication lifecycle for a graph config row (global per `graphId`, ops DB). */
+export const GRAPH_PUBLICATION_STATUSES = ['Draft', 'Published', 'Archived'];
+/** Whether workers should treat the graph as schedulable (global per `graphId`, ops DB). */
+export const GRAPH_OPERATIONAL_STATES = ['NotOperational', 'Ready', 'Running'];
+/** Default when `publicationStatus` is missing on a persisted graph config (legacy rows). */
+export const DEFAULT_GRAPH_PUBLICATION_STATUS = 'Draft';
+/** Default when `operationalState` is missing on a persisted graph config (legacy rows). */
+export const DEFAULT_GRAPH_OPERATIONAL_STATE = 'NotOperational';
+//# sourceMappingURL=contracts.js.map

package/dist/execution-matrix/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/execution-matrix/contracts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAmBH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,aAAa;IACb,aAAa;IACb,WAAW;IACX,QAAQ;IACR,SAAS;CACD,CAAC;AAyCX,qFAAqF;AACrF,MAAM,CAAC,MAAM,sCAAsC,GAAG,KAAK,CAAC;AAmD5D,4DAA4D;AAC5D,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAC9C,oEAAoE;AACpE,MAAM,CAAC,MAAM,mCAAmC,GAAG,IAAI,CAAC;AACxD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,4BAA4B,GAAG,2BAA2B,CAAC;AAExE,iDAAiD;AACjD,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAcxC,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,YAAY,EAAE,aAAa,CAAU,CAAC;AAE5E,oFAAoF;AACpF,MAAM,CAAC,MAAM,+BAA+B,GAAG,UAAmB,CAAC;AACnE,MAAM,CAAC,MAAM,gCAAgC,GAAG,WAAoB,CAAC;AACrE,MAAM,CAAC,MAAM,6BAA6B,GAAG,SAAkB,CAAC;AAChE,MAAM,CAAC,MAAM,iCAAiC,GAAG,YAAqB,CAAC;AAEvE,0FAA0F;AAC1F,MAAM,CAAC,MAAM,6BAA6B,GAAG,kBAA2B,CAAC;AAEzE;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,QAAiB,CAAC;AAma7D,mFAAmF;AACnF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,CAAU,CAAC;AAGtF,4FAA4F;AAC5F,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,gBAAgB,EAAE,OAAO,EAAE,SAAS,CAAU,CAAC;AAyBxF,6FAA6F;AAC7F,MAAM,CAAC,MAAM,gCAAgC,GAA2B,OAAO,CAAC;AAEhF,4FAA4F;AAC5F,MAAM,CAAC,MAAM,+BAA+B,GAA0B,gBAAgB,CAAC"}