@exellix/graph-engine 6.0.0

package/dist/src/types/refs.d.ts

@@ -0,0 +1,747 @@
+import type { SmartInputConfig } from './aiTasksDerivedTypes.js';
+import type { TaskNodeTaskConfiguration } from './taskNodeConfiguration.js';
+/**
+ * One step in `TaskNode.executionPipeline`. Same shape as `ExecutionStepOption` in `options.ts`
+ * (declared here to avoid a circular import between `refs.ts` and `options.ts`).
+ */
+export type TaskNodeExecutionPipelineStep = {
+    phase: 'pre' | 'main' | 'post';
+    type: string;
+    config?: unknown;
+};
+/**
+ * Type references for graph execution
+ */
+/**
+ * Explicit AI model selection carried by graph model/runtime contracts.
+ * Values may be concrete model ids or runtime aliases resolved before `runTask`.
+ */
+export type GraphAiModelConfig = {
+    xynthesisModel: string;
+    skillModel: string;
+};
+/** Runtime alias map used to resolve GraphAiModelConfig values before dispatch. */
+export type GraphModelAliasConfig = Record<string, string>;
+/** Runtime overrides for a single task node, stored at GraphRuntimeObject.nodes[nodeId]. */
+export type TaskNodeRuntimeObject = {
+    modelConfig?: GraphAiModelConfig;
+    aliasConfig?: GraphModelAliasConfig;
+};
+/** Backwards-readable alias for per-node runtime overrides keyed by task node id. */
+export type GraphRuntimeNodeConfig = TaskNodeRuntimeObject;
+/** Schema version for structured record gates on `conditions.dataFilters` (and optional `graphEntry.dataFilters`). */
+export declare const EXELLIX_STRUCTURED_DATA_FILTERS_V1: "exellix.dataFilters.v1";
+/**
+ * Deterministic JSON gate: same recursive shape as {@link GraphPredicate}, but every leaf `path`
+ * must be `data` or `data.*` and is evaluated against the host-supplied **record** object (the
+ * object whose properties back those paths). See `evaluateStructuredDataFilters` in the runtime.
+ */
+export type StructuredDataFiltersV1 = {
+    version: typeof EXELLIX_STRUCTURED_DATA_FILTERS_V1;
+    when: GraphPredicate;
+};
+/** Legacy catalog ids (`string[]`) or structured v1 gate. */
+export type ConditionsDataFilters = string[] | StructuredDataFiltersV1;
+export type GraphPredicate = {
+    /** Dot-path into evaluation context (executionMemory/variables/jobMemory/taskMemory). */
+    path: string;
+    /** True when the value is neither null nor undefined. */
+    exists?: boolean;
+    /** Strict equality comparison. */
+    eq?: any;
+} | {
+    all: GraphPredicate[];
+} | {
+    any: GraphPredicate[];
+} | {
+    not: GraphPredicate;
+};
+export interface GraphEdge {
+    /** Source node id. */
+    from: string;
+    /** Destination node id (depends on `from`). */
+    to: string;
+    /** Optional predicate controlling whether this dependency edge is active. */
+    when?: GraphPredicate;
+    [key: string]: any;
+}
+export type OutputSchema = {
+    type: 'object';
+    required?: string[];
+    properties?: Record<string, {
+        type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    }>;
+    additionalProperties?: boolean;
+};
+/**
+ * Optional authoring / documentation block: human-readable titles and questions next to framework ids.
+ * Not read by exellix-graph execution; not merged into `RunTaskRequest.narrix` (only `metadata.narrix` is forwarded).
+ */
+/**
+ * Classifies the role of a node in terms of question-answering, for graph-browsing tools and human readers.
+ * - `contextual-data`  — scoped-data-reader reading background context for this entity
+ * - `upstream-verdict` — scoped-data-reader reading a verdict written by an earlier graph in the pipeline
+ * - `inference`        — deterministic-rule deriving a verdict/label from available data
+ * - `routing`          — deterministic-rule deciding which execution branch to follow
+ * - `llm-analysis`     — professional-answer asking an LLM to reason over evidence
+ * - `assembly`         — scoped-answer-assembler merging node outputs into a persistence payload
+ * - `persistence`      — scoped-answer-writer writing assembled answers to x-scoped-data
+ */
+export type GraphReadabilityKind = 'contextual-data' | 'upstream-verdict' | 'inference' | 'routing' | 'llm-analysis' | 'assembly' | 'persistence';
+export type GraphReadability = {
+    /** Short label when scanning graph JSON or building UIs */
+    title?: string;
+    /** Plain-language question or intent (may match or shorten `inputs.question`) */
+    asks?: string;
+    /** Classifies the node's question-answering role — see GraphReadabilityKind */
+    kind?: GraphReadabilityKind;
+    /**
+     * Key fields this node reads from scoped storage.
+     * Applicable to `contextual-data` and `upstream-verdict` nodes.
+     * Makes the scope-map contents visible without cross-referencing the scopingMapId.
+     * Declares expected answer keys for authors and graph UIs; the engine loads the full scoped `answer` row (see `.docs/exellix-graph-format.md` — scoped entity reads vs graph-level reads).
+     */
+    reads?: string[];
+    /**
+     * Possible output values or tier names this node can produce.
+     * Applicable to `inference`, `routing`, and `llm-analysis` nodes.
+     * For routing nodes, each entry describes a tier and its gate condition.
+     */
+    produces?: string[];
+    /** Echo ids that appear elsewhere on the node for grep-friendly reading */
+    ids?: {
+        narrixQuestionId?: string;
+        skillKey?: string;
+    };
+};
+export type FinalizerInputBinding = {
+    type: 'executionMemoryPath';
+    path: string;
+    optional?: boolean;
+} | {
+    type: 'outputsMemoryPath';
+    path: string;
+    optional?: boolean;
+} | {
+    type: 'literal';
+    value: unknown;
+};
+export type GraphResponseMissingBehavior = 'omit' | 'null';
+export type GraphResponseSelector = {
+    type: 'outputsMemoryPath';
+    path: string;
+} | {
+    type: 'executionMemoryPath';
+    path: string;
+} | {
+    type: 'executionPath';
+    path: string;
+} | {
+    type: 'nodeMetadata';
+    nodeId: string;
+    path: string;
+} | {
+    type: 'nodeInputsConfig';
+    nodeId: string;
+    path: string;
+}
+/** @deprecated Use `nodeInputsConfig`. */
+ | {
+    type: 'nodeInputs';
+    nodeId: string;
+    path: string;
+} | {
+    type: 'literal';
+    value: unknown;
+} | {
+    type: 'firstPresent';
+    sources: GraphResponseSelector[];
+};
+export type GraphResponseShape = unknown;
+export type GraphResponseDefinition = {
+    /** Default: "omit". When "null", missing selector values are materialized as null. */
+    missing?: GraphResponseMissingBehavior;
+    shape: GraphResponseShape;
+};
+/** @deprecated Use root-level GraphResponseDefinition at GraphModelObject.response. */
+export type GraphResponseMappingTarget = 'finalOutput';
+/** @deprecated Use GraphResponseMissingBehavior. */
+export type GraphResponseMappingMissingBehavior = GraphResponseMissingBehavior;
+/** @deprecated Use GraphResponseSelector. */
+export type GraphResponseMappingSelector = GraphResponseSelector;
+/** @deprecated Use root-level GraphResponseDefinition at GraphModelObject.response. */
+export type GraphResponseMapping = {
+    version: 'graphResponseMapping.v1';
+    target?: GraphResponseMappingTarget;
+    /** Default: "omit". When "null", missing selector values are materialized as null. */
+    missing?: GraphResponseMappingMissingBehavior;
+    shape: unknown;
+};
+export type AggregateExpr = {
+    kind: 'input';
+    name: string;
+} | {
+    kind: 'literal';
+    value: unknown;
+};
+export type QuestionDrivenItemSpec = {
+    /** Node id to pull the question text from. */
+    nodeId: string;
+    /**
+     * Dot-path under the node definition to read the question from.
+     * Default: "inputs.question"
+     */
+    questionPath?: string;
+    /**
+     * Dot-path under executionMemory where the node wrote its output.
+     * Default: node.executionMapping.path (if present)
+     */
+    answerPath?: string;
+    /**
+     * When true and the answer path resolves to a failed node marker or is missing, `answer` becomes `null`.
+     */
+    optional?: boolean;
+};
+export type ReportSchemaSectionSpec = {
+    /** Dot-path in executionMemory to pull the section value from. */
+    path: string;
+    /** Human-readable title for this section. */
+    title?: string;
+    optional?: boolean;
+};
+export type AggregateFinalizerConfig = {
+    strategy: 'object-map';
+    map: Record<string, AggregateExpr>;
+    omitUndefined?: boolean;
+} | {
+    /**
+     * Build a canonical question-driven response object.
+     * Each entry produces: { question, answer } under the configured output key.
+     */
+    strategy: 'question-driven';
+    /** Optional literal contract version to include at top-level. */
+    contractVersion?: string;
+    /** Map output keys → node specs. */
+    items: Record<string, QuestionDrivenItemSpec>;
+    /** Optional extra metadata to include at top-level from executionMemory or outputsMemory. */
+    meta?: Record<string, {
+        type: 'executionMemoryPath' | 'outputsMemoryPath';
+        path: string;
+        optional?: boolean;
+    }>;
+} | {
+    /**
+     * Assemble a structured multi-section report from executionMemory.
+     * Each section key maps to a dot-path.  collect_tags gathers all
+     * epistemic tags across sections.
+     */
+    strategy: 'report-schema';
+    /** Map of output key → section spec (path + optional title). */
+    sections: Record<string, ReportSchemaSectionSpec>;
+    /** When true, scan all section values for CONFIRMED/INFERRED/ASSUMED/UNKNOWN and emit collected_tags. */
+    collect_tags?: boolean;
+    /** Optional literal fields merged at top level. */
+    meta?: Record<string, unknown>;
+};
+export type BundleFinalizerConfig = {
+    strategy: 'bundle';
+    includeInputs: string[];
+};
+export type SelectFinalizerConfig = {
+    strategy: 'select';
+    selector: {
+        type: 'firstPresent' | 'byInputValue';
+        order?: string[];
+        selectorInput?: string;
+        cases?: Record<string, string>;
+    };
+};
+export type UtilityExecutionPolicy = 'debug' | 'standard' | 'batch-prod';
+export type SynthesizeFinalizerConfig = {
+    strategy: 'synthesize';
+    /** Utility skill key resolved by `@exellix/ai-tasks` (e.g. catalog utilities such as `xynthesis/finalize`). */
+    utilityKey: string;
+    templateId: string;
+    outputContractId?: string;
+    executionPolicy?: UtilityExecutionPolicy;
+};
+export interface FinalizerNode {
+    id: string;
+    type: 'finalizer';
+    finalizerType: 'aggregate' | 'compose' | 'select' | 'bundle' | 'synthesize';
+    inputs: Record<string, FinalizerInputBinding>;
+    /** Transitional: runtime validation narrows by finalizerType; implemented finalizers export typed configs. */
+    config: AggregateFinalizerConfig | BundleFinalizerConfig | SelectFinalizerConfig | SynthesizeFinalizerConfig | Record<string, unknown>;
+    /** Writes selected finalizer result fields into graph-owned outputsMemory for final response assembly. */
+    outputMapping?: TaskNodeResultMapping;
+    outputSchema?: OutputSchema;
+    [key: string]: any;
+}
+/**
+ * Allowlisted task-node `metadata`: descriptive / planning only.
+ * Execution wiring lives on {@link TaskNode.taskConfiguration}.
+ */
+export type TaskNodePureMetadata = {
+    graphReadability?: GraphReadability;
+    catalogBinding?: CatalogBinding;
+    catalogRequest?: CatalogRequestEntry;
+    /** Display / tracing label (not merged into template variables from metadata). */
+    name?: string;
+    description?: string;
+    /** Declarative integration target; runtime does not branch on this key. */
+    exellixContractTarget?: unknown;
+};
+export type TaskNodeResultMapping = {
+    path: string;
+    mode?: 'replace' | 'append' | 'merge';
+    map?: {
+        [targetKey: string]: string;
+    };
+    fields?: string[];
+};
+export type TaskNodeConditionParameters = Record<string, unknown>;
+/** When true, invert the evaluator result after runx returns. */
+export type TaskNodeConditionNegate = {
+    negate?: boolean;
+};
+export type TaskNodeJsonConditionOptions = {
+    jsonConditionFormat?: 'auto' | 'jsonlogic' | 'jsonata' | 'filter-predicate' | 'custom';
+    timeoutMs?: number;
+};
+export type TaskNodeJsonCondition = TaskNodeConditionNegate & {
+    condition: string | Record<string, unknown> | unknown[];
+    parameters?: TaskNodeConditionParameters;
+    options?: TaskNodeJsonConditionOptions;
+};
+export type TaskNodeJsConditionFunction = TaskNodeConditionNegate & {
+    conditionFunctionId: string;
+    parameters?: TaskNodeConditionParameters;
+};
+export type TaskNodeAiCondition = TaskNodeConditionNegate & {
+    condition: string;
+    parameters?: TaskNodeConditionParameters;
+    mode?: 'hybrid' | 'model';
+    model?: string;
+};
+/** Gates evaluated by graph-engine (runx) before a task node runs. */
+export type TaskNodeConditionWhen = {
+    jsonConditions?: TaskNodeJsonCondition;
+    jsConditionFunction?: TaskNodeJsConditionFunction;
+    aiCondition?: TaskNodeAiCondition;
+};
+/**
+ * Declarative gating for when this node should run.
+ *
+ * - **`jsonConditions` / `jsConditionFunction` / `aiCondition`:** evaluated via runx (see `evaluateTaskNodeConditions`).
+ * - **`dataFilters` (`string[]`):** opaque catalog ids — not evaluated by graph-engine.
+ * - **`narratives`:** authoring / tooling only.
+ */
+export type TaskNodeConditions = {
+    narratives?: string[];
+    /** Opaque catalog reference ids only — not evaluated by graph-engine. */
+    dataFilters?: string[];
+    jsonConditions?: TaskNodeJsonCondition;
+    jsConditionFunction?: TaskNodeJsConditionFunction;
+    aiCondition?: TaskNodeAiCondition;
+};
+export type ModelConfigCase = {
+    when?: TaskNodeConditionWhen;
+    modelConfig: GraphAiModelConfig;
+};
+/** Canonical authoring shape for graph and taskConfiguration model selection. */
+export type ModelConfigSelection = {
+    cases: ModelConfigCase[];
+};
+export interface TaskNode {
+    id: string;
+    type?: string;
+    skillKey?: string;
+    /**
+     * Static task-scoped knowledge references declared by the graph model.
+     * Node/task-scoped knowledge refs. Runtime resolvers may use these refs to
+     * enrich this node's outbound `RunTaskRequest.taskMemory.knowledge`; resolved
+     * content must not be authored back into the model.
+     */
+    taskKnowledge?: string[];
+    /**
+     * **Removed in 5.x** — `data.skillKey` / `data.variables` are no longer accepted; the runtime
+     * reads only `node.skillKey` and `node.variables`. The optional `data` bag may still carry
+     * arbitrary host fields, but the canonical validator rejects `skillKey` / `variables` here.
+     */
+    data?: Record<string, any>;
+    metadata?: TaskNodePureMetadata & {
+        /** Synthetic boundary marker from {@link materializeVirtualBoundaryDiagram}; not execution config. */
+        __exellixVirtualBoundary?: boolean;
+    };
+    /**
+     * Execution-facing settings for this node (`runTask`, Narrix, pipelines, local skills, retries).
+     */
+    taskConfiguration?: TaskNodeTaskConfiguration;
+    variables?: Record<string, any>;
+    memory?: {
+        taskMemory?: any;
+        jobMemory?: any;
+    };
+    /** Writes selected node result fields into task-visible executionMemory for downstream execution. */
+    executionMapping?: TaskNodeResultMapping;
+    jobContextMapping?: {
+        path?: string;
+        mode?: 'replace' | 'append' | 'merge';
+        map?: {
+            [targetKey: string]: string;
+        };
+        fields?: string[];
+    };
+    scope?: {
+        contextualKnowledge?: Array<{
+            list: string;
+            select?: string[];
+            filter?: {
+                where?: Array<{
+                    path: string;
+                    eq?: any;
+                    eqAny?: any[];
+                }>;
+                limit?: number;
+                orderBy?: Array<{
+                    path: string;
+                    direction: 'asc' | 'desc';
+                }>;
+            };
+        }>;
+    };
+    /**
+     * Runtime payload bindings only (`executionMemoryPath` / legacy memory `$path` refs).
+     * See `taskVariable` for prompts and graph-variable hooks.
+     */
+    inputsConfig?: Record<string, unknown>;
+    /** @deprecated Prefer `inputsConfig`. */
+    inputBindings?: Record<string, unknown>;
+    /**
+     * @deprecated Prefer `inputsConfig` — name collides with `runtime.inputs` (caller bag).
+     */
+    inputs?: Record<string, any>;
+    /**
+     * Dynamic task configuration: prompts, literals, and `{ "$path": "variables.*" }` refs.
+     * Not execution-memory payload wires (those belong in `inputsConfig`).
+     */
+    taskVariable?: Record<string, unknown>;
+    /**
+     * Passthrough smart-input path list for `@exellix/ai-tasks` (graph-engine validates allowed roots only).
+     */
+    smartInput?: SmartInputConfig;
+    /**
+     * Optional deterministic output checks before `executionMapping` is applied (see `executeNode` / `validateNodeOutput`).
+     */
+    outputValidation?: TaskOutputValidation;
+    /**
+     * Per-node execution pipeline (pre / main / post). Same semantics as `ExecuteGraphOptions.executionPipeline`.
+     * Read by `executeNode` and `ExellixGraphRuntime` when not overridden by options / execution.
+     */
+    executionPipeline?: TaskNodeExecutionPipelineStep[];
+    /** Optional runx-backed gates; opaque dataFilters / narratives are not evaluated by graph-engine. */
+    conditions?: TaskNodeConditions;
+    [key: string]: any;
+}
+/** Shape used by runtime output validation (`executeNode`). */
+export type TaskOutputValidation = {
+    rules?: Array<{
+        path: string;
+        type: 'boolean' | 'string' | 'number' | 'object' | 'array';
+        required?: boolean;
+    }>;
+};
+export type GraphNode = TaskNode | FinalizerNode;
+/**
+ * Which catalog family a binding or gap request refers to.
+ * Exellix-graph-engine does not branch on these values at execution time.
+ */
+export type CatalogPlanningKind = 'scoped-question' | 'discovery-definition';
+/**
+ * Workflow status for a catalog gap request (tooling only).
+ */
+export type CatalogRequestStatus = 'required' | 'draft' | 'submitted' | string;
+/**
+ * Binds a task node to a catalog entry (scoped question or discovery definition).
+ * **Planning only:** editors use this as source of truth; runtime uses `taskConfiguration.narrix`,
+ * `taskConfiguration.scopingMapId`, etc., unless an external tool syncs them. Safe to omit; ignored by the executor.
+ *
+ * `discovery-definition` is a first-class literal for Narrix-aligned discovery catalog entries.
+ */
+export type CatalogBinding = {
+    catalogType: CatalogPlanningKind | string;
+    catalogId: string;
+    /** Catalog semver or label when known; omit during early authoring. */
+    version?: string;
+    /** Optional notes for editor UIs (not consumed by exellix-graph execution). */
+    notes?: string;
+};
+/**
+ * Planning vocabulary for a discovery-definition catalog item: mirrors Narrix-oriented docs and
+ * {@link NarrixPreProcessorConfig} without implying the executor reads this shape from bindings.
+ * All fields optional so editors can store partial snapshots while authoring.
+ */
+export type DiscoveryDefinitionPlanningFields = {
+    title?: string;
+    purpose?: string;
+    datasetId?: string;
+    layer?: string;
+    narrativeTypeIds?: string[];
+    enableWebScope?: boolean;
+    /** Discovery notes / rationale for editors and dashboards only. */
+    discoveryNotes?: string;
+    /** Expected semantic outputs (signals/stories, etc.) — planning hints only. */
+    expectedSemanticOutputs?: string[];
+    /** Compatible task / skill identifiers for this definition (planning). */
+    compatibleTaskTypes?: string[];
+};
+type CatalogRequestEntryShared = {
+    status: CatalogRequestStatus;
+    requestedId: string;
+    reason: string;
+    /** Optional short label; discovery gaps often omit until copy exists. */
+    title?: string;
+    requestedByNodeId?: string;
+};
+/**
+ * Graph- or node-level request for a missing scoped-question catalog item.
+ */
+export type ScopedQuestionCatalogRequestEntry = CatalogRequestEntryShared & {
+    catalogType: 'scoped-question';
+    asks: string;
+    entityType: string;
+    proposedScopingMapId?: string;
+    planningNotes?: string;
+};
+/**
+ * Graph- or node-level request for a missing discovery-definition catalog item
+ * (planning alignment with Narrix-oriented fields — not applied to `metadata.narrix` by the executor).
+ * Narrix-aligned fields are optional so in-flight gap declarations stay valid.
+ */
+export type DiscoveryDefinitionCatalogRequestEntry = CatalogRequestEntryShared & {
+    catalogType: 'discovery-definition';
+} & DiscoveryDefinitionPlanningFields;
+/** Alias matching client naming for the discovery gap variant. */
+export type DiscoveryDefinitionCatalogRequest = DiscoveryDefinitionCatalogRequestEntry;
+/**
+ * Declares a required catalog item that does not exist yet (gap / feature request).
+ */
+export type CatalogRequestEntry = ScopedQuestionCatalogRequestEntry | DiscoveryDefinitionCatalogRequestEntry;
+/**
+ * Semantic class of data a graph expects at Layer 01. Combinations are represented
+ * by multiple `GraphEntryInputSpec` entries on `metadata.graphEntry.inputs`.
+ */
+export type GraphEntryInputKind = 'record' | 'query' | 'user-input' | 'content' | 'metadata' | 'execution';
+export type GraphEntryValueInputKind = Exclude<GraphEntryInputKind, 'execution'>;
+/**
+ * Design-time declaration shared by graph entry inputs.
+ * **Declarative only:** core runtime does not validate or coerce these specs.
+ */
+export type GraphEntryInputSpecBase = {
+    /** Semantic input class, e.g. `record`, `query`, `user-input`, `content`, or `execution`. */
+    kind: GraphEntryInputKind;
+    /** Stable name for tooling/templates when the path is not enough. */
+    name?: string;
+    /** One-line label for graph authors and UIs. */
+    title?: string;
+    /** Longer human-readable description for editors, catalogs, and docs. */
+    description?: string;
+    /** Defaults to true for authoring intent; runtime does not enforce it today. */
+    required?: boolean;
+    /** Optional JSON Schema for this specific input value. Validators may use it; core runtime does not. */
+    schema?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+/**
+ * Design-time declaration of one caller-supplied value in the graph execution object.
+ * Paths are dot-paths under the merged `execution` object, usually `input.*`.
+ */
+export type GraphEntryValueInputSpec = GraphEntryInputSpecBase & {
+    kind: GraphEntryValueInputKind;
+    /** Dot-path under merged `execution` where this input is expected, e.g. `input.subnetId`. */
+    path: string;
+};
+/**
+ * Design-time declaration of a prior graph execution used as this graph's input.
+ * A host/orchestrator can use `graphId` and `metadataFilter` to find the source execution,
+ * then materialize it at `path` before calling `executeGraph`.
+ */
+export type GraphEntryExecutionInputSpec = Omit<GraphEntryInputSpecBase, 'kind'> & {
+    kind: 'execution';
+    /** Source graph id whose completed execution should be used as input. */
+    graphId: string;
+    /** Metadata fields used by host tooling to select the matching source execution. */
+    metadataFilter?: Record<string, unknown>;
+    /** Dot-path under merged `execution` where the selected graph execution is expected. */
+    path?: string;
+};
+/**
+ * Design-time declaration of one graph entry input.
+ */
+export type GraphEntryInputSpec = GraphEntryValueInputSpec | GraphEntryExecutionInputSpec;
+/**
+ * Layer 01 (graph entry): declares what callers should supply in `ExecuteGraphOptions.execution`
+ * after merge — the seed for `execution.input.*` and related paths first-wave nodes read.
+ * **Declarative only:** `executeGraph` does not validate this object; it is exposed via
+ * `variables.__graphModel` for tools, composers, and documentation (see `.docs/graph-io-visibility.md`).
+ */
+export type GraphEntryContract = {
+    /** One-line summary for authors and UIs. */
+    summary?: string;
+    /**
+     * Optional structured gate evaluated once at graph-run start against `runtime.executionMemory.input`
+     * (same shape as `TaskNodeConditions.dataFilters`). Legacy `string[]` ids are not evaluated here.
+     */
+    dataFilters?: ConditionsDataFilters;
+    /**
+     * Dot-paths under merged `execution` that first-wave nodes expect (e.g. `input.subnetId`,
+     * `input.entityId`, `input.vulnerabilityId`). Same convention as `metadata.entityIdPath` roots.
+     */
+    requiredExecutionPaths?: string[];
+    /**
+     * Semantic entry inputs this graph is designed to work with. Use multiple entries for combinations
+     * (for example, `record` + `query`).
+     */
+    inputs?: GraphEntryInputSpec[];
+    /**
+     * Optional JSON Schema (e.g. draft 2020-12) for the merged `execution` object. Validators may use it; core runtime does not.
+     */
+    executionSchema?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+/**
+ * @deprecated Use root-level {@link GraphModelObject.response}. The final response shape is executable
+ * graph contract, not document metadata.
+ */
+export type GraphResponseContract = {
+    summary?: string;
+    /**
+     * Execution paths typically read after a successful run (e.g. `finalOutput`, `_trace.nodes`).
+     * UIs may also read `runLog`, `runLogTruncated`, and `logxerCorrelationId` on the graph result object.
+     */
+    notableExecutionPaths?: string[];
+    /**
+     * Optional JSON Schema for `finalOutput` (finalizer product). Core runtime does not validate.
+     */
+    finalOutputSchema?: Record<string, unknown>;
+    /** @deprecated Move executable response shaping to root `graph.response`. */
+    responseMapping?: GraphResponseMapping;
+    [key: string]: unknown;
+};
+export type GraphExecutionMode = 'forward' | 'backward' | 'hybrid';
+export type GraphOutputMode = 'mappedAggregation' | 'lastExitNode';
+export type GraphFlowOutline = 'linearSequence' | 'convergingParallelFlow';
+export type GraphCoreObjective = {
+    /** Dynamic property name used on every `stepsResponses` item. Default: "coreObjective". */
+    propertyName: string;
+    /** Dot-path resolved from graph/run context. Supported roots: input, execution, variables, jobMemory, taskMemory, job. */
+    sourcePath: string;
+};
+/**
+ * Human-readable labels for how a graph's node responses should be described in UIs and docs.
+ * Runtime uses these keys when building `stepsResponses`.
+ */
+export type GraphNodesResponses = {
+    singular: string;
+    plural: string;
+};
+/**
+ * Graph-level execution defaults and authoring labels.
+ * Planner mode still comes from `GraphExecutionRequest.runtime.mode`; response shaping belongs to
+ * root-level `GraphModelObject.response`.
+ */
+export type GraphExecutionDefaults = {
+    mode?: GraphExecutionMode;
+    goalNodeId?: string;
+    dimension?: string;
+    outputMode?: GraphOutputMode;
+    coreObjective?: GraphCoreObjective;
+    nodesResponses?: GraphNodesResponses;
+    /** Metadata-only outline for tools/docs; runtime does not branch on this value. */
+    flowOutline?: GraphFlowOutline;
+};
+/**
+ * Graph-document metadata: domain model, contracts, catalog hints, authoring.
+ * Declare product-specific shapes here; exellix-graph forwards values to `variables.__graphModel`
+ * and inspection without interpreting keys.
+ */
+export interface GraphDocumentMetadata {
+    /** Short title (tooling, UIs). */
+    name?: string;
+    /** Longer description for authors or catalogs. */
+    description?: string;
+    /** Integration / contract target blob (declarative; runtime does not branch on it). */
+    exellixContractTarget?: unknown;
+    /**
+     * Layer 01 — expected execution seed / input contract (see {@link GraphEntryContract}).
+     */
+    graphEntry?: GraphEntryContract;
+    /** @deprecated Move final response contract to root `graph.response`. */
+    graphResponse?: GraphResponseContract;
+    /**
+     * Graph execution defaults and labels.
+     * Planner mode is still selected by `executeGraph({ model, runtime }).runtime.mode` and defaults to `forward`;
+     * output labels in this block shape `stepsResponses`, not `ExecuteGraphResult.finalOutput`.
+     */
+    graphExecution?: GraphExecutionDefaults;
+    /**
+     * Planning-only: formal catalog gap requests (scoped questions and/or discovery definitions).
+     * Not enforced or interpreted by the executor — for editors, dashboards, and gap tracking.
+     */
+    catalogRequests?: CatalogRequestEntry[];
+    /** Optional nested bucket for namespaced extensions. */
+    extensions?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Merged graph document model is exposed under this key in merged execution `variables`. */
+export declare const EXELLIX_GRAPH_MODEL_VARIABLE_KEY: "__graphModel";
+/** Returns `graph.metadata` when present (plain object); otherwise `{}`. */
+export declare function mergeGraphDocumentModel(graph: Graph): GraphDocumentMetadata;
+export interface GraphModelObject {
+    id: string;
+    /** Optional static model version for authoring, storage, and replay/audit tooling. */
+    version?: string;
+    /**
+     * Graph-level default AI model selection. Runtime aliases are resolved from
+     * GraphRuntimeObject.aliasConfig / nodes[nodeId].aliasConfig before runTask.
+     */
+    modelConfig?: ModelConfigSelection;
+    /**
+     * Static graph-level knowledge references. Runtime resolvers use these refs
+     * for outbound `RunTaskRequest.jobMemory.knowledge` across the graph run.
+     */
+    jobKnowledge?: string[];
+    /** Canonical 5.x: nodes is always a `GraphNode[]` array. Record-keyed nodes are rejected at load. */
+    nodes: GraphNode[];
+    edges?: GraphEdge[];
+    variables?: Record<string, any>;
+    /**
+     * Executable graph-level final response contract. `ExecuteGraphResult.finalOutput`
+     * is resolved from this shape after nodes and the terminal finalizer/barrier complete.
+     */
+    response: GraphResponseDefinition;
+    /**
+     * Graph-level metadata (domain / contract / catalog). Copied into execution variables
+     * as {@link EXELLIX_GRAPH_MODEL_VARIABLE_KEY}; see {@link mergeGraphDocumentModel}.
+     */
+    metadata?: GraphDocumentMetadata;
+}
+/** Backwards-compatible type alias for the static graph model object. */
+export type Graph = GraphModelObject;
+export interface Job {
+    /**
+     * Host correlation id for this run (mirrors `runtime.jobId`) after normalization.
+     * You may omit `id` / `job.jobId` on input when `runtime.jobId` is passed at the graph call; the runtime sets both.
+     */
+    id?: string;
+    /** Same as `id` when both set — used by injected runtime and `runTask.jobId`. */
+    jobId?: string;
+    /** Semantic class of job, distinct from unique `id`. Forwarded to `@exellix/ai-tasks` as `jobTypeId` when set. */
+    jobType?: string;
+    /** Explicit catalog/job classification id; wins over `jobType` when both are set for `runTask.jobTypeId`. */
+    jobTypeId?: string;
+    jobVariables?: Record<string, any>;
+    agentId?: string;
+    [key: string]: any;
+}
+export {};