clinkx 0.1.10 → 0.2.1

package/clinkx-workflows/dist/fingerprint.js

@@ -0,0 +1,143 @@
+/**
+ * Fingerprint generation for referenced adapter configs (1-3).
+ *
+ * Hashes the complete post-load normalized config of every adapter/role
+ * actually referenced by a workflow definition. The fingerprint is used
+ * for fast mismatch rejection on resume — if it doesn't match, the run
+ * is rejected without needing to diff the full snapshot.
+ *
+ * What is included:
+ * - All CliAdapterConfigSchema fields for referenced adapters
+ * - Resolved role prompt contents (not just prompt_file paths)
+ * - Explicit child env controls (CLINKX_MAX_CONCURRENT, etc.)
+ *
+ * What is NOT included:
+ * - Unreferenced adapters
+ * - Full tools/list enum
+ * - serverInfo.version (unreliable — hardcoded vs package.json divergence)
+ */
+import { createHash } from "node:crypto";
+import { logger } from "./logger.js";
+/**
+ * Collect the set of (cli_name, role) pairs actually referenced by a workflow definition.
+ * Only these adapters are included in the fingerprint.
+ */
+export function collectReferencedAdapters(definition) {
+    const refs = new Set();
+    for (const stage of definition.stages) {
+        for (const call of stage.calls) {
+            refs.add(call.cli_name);
+        }
+    }
+    return refs;
+}
+/**
+ * Collect the set of (cli_name, role) pairs for role prompt resolution.
+ * Returns keys in "cli_name.role" format.
+ */
+export function collectReferencedRoles(definition) {
+    const refs = new Set();
+    for (const stage of definition.stages) {
+        for (const call of stage.calls) {
+            refs.add(`${call.cli_name}.${call.role}`);
+        }
+    }
+    return refs;
+}
+/**
+ * Build a ChildConfigSnapshot from the workflow definition and runtime context.
+ *
+ * @param definition - Normalized workflow definition (determines which adapters are referenced)
+ * @param adapterConfigs - Complete post-load adapter configs keyed by adapter name
+ * @param resolvedPrompts - Resolved role prompt contents keyed by "adapter.role"
+ * @param childEnv - Explicit child env controls applied at spawn time
+ * @returns Snapshot containing only referenced adapters
+ */
+export function buildConfigSnapshot(definition, adapterConfigs, resolvedPrompts, childEnv) {
+    const referencedAdapters = collectReferencedAdapters(definition);
+    const referencedRoles = collectReferencedRoles(definition);
+    // Filter to only referenced adapters
+    const filteredAdapters = {};
+    for (const name of referencedAdapters) {
+        const config = adapterConfigs[name];
+        if (config !== undefined) {
+            filteredAdapters[name] = config;
+        }
+    }
+    // Filter to only referenced role prompts
+    const filteredPrompts = {};
+    for (const key of referencedRoles) {
+        const prompt = resolvedPrompts[key];
+        if (prompt !== undefined) {
+            filteredPrompts[key] = prompt;
+        }
+    }
+    return {
+        adapters: filteredAdapters,
+        resolvedPrompts: filteredPrompts,
+        childEnv,
+    };
+}
+/**
+ * Compute a deterministic SHA-256 hash of a ChildConfigSnapshot.
+ *
+ * Uses JSON.stringify with sorted keys to ensure deterministic serialization
+ * regardless of property insertion order.
+ */
+export function hashSnapshot(snapshot) {
+    const serialized = JSON.stringify(snapshot, sortedReplacer);
+    return createHash("sha256").update(serialized, "utf-8").digest("hex");
+}
+/**
+ * Generate a complete Fingerprint from a ChildConfigSnapshot.
+ *
+ * This is the primary API for Phase 4 to persist and compare.
+ */
+export function generateFingerprint(snapshot) {
+    const hash = hashSnapshot(snapshot);
+    logger.debug({
+        adapter_count: Object.keys(snapshot.adapters).length,
+        prompt_count: Object.keys(snapshot.resolvedPrompts).length,
+        env_count: Object.keys(snapshot.childEnv).length,
+        hash,
+    }, "generated config fingerprint");
+    return {
+        algorithm: "sha256",
+        hash,
+        computedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Compare two fingerprints for equality.
+ * Only compares algorithm and hash — computedAt is informational.
+ */
+export function fingerprintsMatch(a, b) {
+    return a.algorithm === b.algorithm && a.hash === b.hash;
+}
+/**
+ * End-to-end fingerprint generation from workflow definition and runtime context.
+ *
+ * Convenience function that builds the snapshot and generates the fingerprint
+ * in one call. Returns both the snapshot (for persistence) and the fingerprint
+ * (for fast comparison).
+ */
+export function generateWorkflowFingerprint(definition, adapterConfigs, resolvedPrompts, childEnv) {
+    const snapshot = buildConfigSnapshot(definition, adapterConfigs, resolvedPrompts, childEnv);
+    const fingerprint = generateFingerprint(snapshot);
+    return { snapshot, fingerprint };
+}
+/**
+ * JSON.stringify replacer that sorts object keys for deterministic serialization.
+ * Arrays maintain their original order (order-significant).
+ */
+function sortedReplacer(_key, value) {
+    if (value != null && typeof value === "object" && !Array.isArray(value)) {
+        const sorted = {};
+        for (const k of Object.keys(value).sort()) {
+            sorted[k] = value[k];
+        }
+        return sorted;
+    }
+    return value;
+}
+//# sourceMappingURL=fingerprint.js.map

package/clinkx-workflows/dist/fingerprint.js.map

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

package/clinkx-workflows/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * clinkx-workflows MCP server entry point (6-9).
+ *
+ * 1. Verify logger writes to stderr (STDIO correctness invariant).
+ * 2. Create the MCP server with workflow tool handlers.
+ * 3. Connect STDIO transport (stdin/stdout for JSON-RPC, stderr for logs).
+ * 4. Wire graceful shutdown via the shutdown coordinator.
+ *
+ * Also serves as the library entry point — re-exports the public API
+ * for in-process integration (Option C).
+ */
+export type { ClinkBackend, ToolCallResult } from "./backend.js";
+export { registerWorkflowTools, getWorkflowToolDefinitions, handleWorkflowToolCall, WORKFLOW_TOOL_NAMES, } from "./workflow-tools.js";
+export type { WorkflowToolsOptions, WorkflowToolDefinition, } from "./workflow-tools.js";
+export { createWorkflowServer } from "./server.js";

package/clinkx-workflows/dist/index.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * clinkx-workflows MCP server entry point (6-9).
+ *
+ * 1. Verify logger writes to stderr (STDIO correctness invariant).
+ * 2. Create the MCP server with workflow tool handlers.
+ * 3. Connect STDIO transport (stdin/stdout for JSON-RPC, stderr for logs).
+ * 4. Wire graceful shutdown via the shutdown coordinator.
+ *
+ * Also serves as the library entry point — re-exports the public API
+ * for in-process integration (Option C).
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createWorkflowServer } from "./server.js";
+import { logger, assertStderrLogger } from "./logger.js";
+export { registerWorkflowTools, getWorkflowToolDefinitions, handleWorkflowToolCall, WORKFLOW_TOOL_NAMES, } from "./workflow-tools.js";
+export { createWorkflowServer } from "./server.js";
+async function main() {
+    assertStderrLogger();
+    const server = createWorkflowServer();
+    const transport = new StdioServerTransport();
+    logger.info("clinkx-workflows MCP server starting (STDIO transport)");
+    await server.connect(transport);
+    // Graceful shutdown: coordinate with any in-flight workflow,
+    // then close the server and exit.
+    const shutdown = async (signal) => {
+        logger.info({ signal }, "shutdown signal received");
+        // ShutdownCoordinator handles in-flight workflow cancellation,
+        // state persistence, and child termination via its own signal handlers.
+        // We just need to close the MCP server transport cleanly.
+        await server.close();
+        process.exit(0);
+    };
+    process.once("SIGTERM", () => void shutdown("SIGTERM").catch(() => process.exit(1)));
+    process.once("SIGINT", () => void shutdown("SIGINT").catch(() => process.exit(1)));
+    logger.info("clinkx-workflows MCP server connected and ready");
+}
+main().catch((err) => {
+    logger.fatal({ err }, "clinkx-workflows failed to start");
+    process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map

package/clinkx-workflows/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAKzD,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,KAAK,UAAU,IAAI;IACjB,kBAAkB,EAAE,CAAC;IAErB,MAAM,MAAM,GAAG,oBAAoB,EAAE,CAAC;IACtC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,MAAM,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;IAEtE,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,6DAA6D;IAC7D,kCAAkC;IAClC,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAc,EAAE,EAAE;QACxC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,0BAA0B,CAAC,CAAC;QACpD,+DAA+D;QAC/D,wEAAwE;QACxE,0DAA0D;QAC1D,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IAEF,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrF,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEnF,MAAM,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAC;AACjE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,kCAAkC,CAAC,CAAC;IAC1D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/clinkx-workflows/dist/loader.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Workflow loader for clinkx-workflows (2-6a, 2-6b, 2-8a, 2-9a, 7-3).
+ *
+ * v1b: loads built-in TypeScript definitions AND external YAML files.
+ * Built-in definitions take precedence over same-named YAML files.
+ * Static validation only — no live child required.
+ *
+ * ## Deferred validation (2-9a)
+ * cli_name and role validation are deliberately kept OUT of the loader.
+ * These are runtime transport concerns:
+ * - cli_name existence depends on child's adapter registry (not available at load time)
+ * - role acceptance depends on per-adapter role configuration
+ * - Current ClinkX exposes only a global role union via tools/list, not per-CLI role maps
+ * This design allows list_workflows to work without a live child.
+ */
+import type { WorkflowDefinition } from "./schema.js";
+import type { ValidatorRegistry } from "./validators/index.js";
+import { type NormalizedWorkflowDefinition } from "./definition-normalizer.js";
+export interface LoaderOptions {
+    /** Absolute path to the templates root directory. */
+    readonly templatesRoot: string;
+    /** Validator registry for schema ID validation. */
+    readonly validatorRegistry: ValidatorRegistry;
+    /**
+     * Absolute path to the workflows directory for YAML discovery.
+     * If not provided, uses CLINKX_WORKFLOWS_PATH env or package-relative default.
+     */
+    readonly workflowsPath?: string | undefined;
+}
+export interface LoadedWorkflow {
+    readonly definition: WorkflowDefinition;
+    readonly normalized: NormalizedWorkflowDefinition;
+    readonly source: "builtin" | "yaml";
+    readonly sourcePath?: string | undefined;
+}
+export interface WorkflowCatalogEntry {
+    readonly definition: WorkflowDefinition;
+    readonly source: "builtin" | "yaml";
+    readonly path?: string | undefined;
+    readonly shadowedYaml: boolean;
+}
+/**
+ * Load and validate a workflow by name.
+ *
+ * Resolution order:
+ * 1. Built-in TypeScript definitions (highest precedence)
+ * 2. External YAML files in the workflows directory
+ *
+ * Returns the validated definition and its normalized (snapshot-ready) form.
+ */
+export declare function loadWorkflow(name: string, options: LoaderOptions): LoadedWorkflow;
+/**
+ * List all available workflows (built-in + YAML).
+ * Built-in definitions take precedence over same-named YAML files.
+ * No live child required.
+ *
+ * @param workflowsPath - Optional absolute path to workflows directory for YAML discovery
+ */
+export declare function listWorkflows(workflowsPath?: string): Map<string, WorkflowDefinition>;
+/**
+ * List workflow definitions with source metadata.
+ * Built-in definitions take precedence over same-named YAML files.
+ */
+export declare function listWorkflowCatalog(workflowsPath?: string): Map<string, WorkflowCatalogEntry>;

package/clinkx-workflows/dist/loader.js

@@ -0,0 +1,371 @@
+/**
+ * Workflow loader for clinkx-workflows (2-6a, 2-6b, 2-8a, 2-9a, 7-3).
+ *
+ * v1b: loads built-in TypeScript definitions AND external YAML files.
+ * Built-in definitions take precedence over same-named YAML files.
+ * Static validation only — no live child required.
+ *
+ * ## Deferred validation (2-9a)
+ * cli_name and role validation are deliberately kept OUT of the loader.
+ * These are runtime transport concerns:
+ * - cli_name existence depends on child's adapter registry (not available at load time)
+ * - role acceptance depends on per-adapter role configuration
+ * - Current ClinkX exposes only a global role union via tools/list, not per-CLI role maps
+ * This design allows list_workflows to work without a live child.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { resolve, extname } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { WorkflowDefinitionSchema } from "./schema.js";
+import { WorkflowValidationError } from "./errors.js";
+import { resolveAllTemplates } from "./template-loader.js";
+import { normalizeForSnapshot } from "./definition-normalizer.js";
+import { getBuiltinWorkflows } from "./workflows/index.js";
+import { getWorkflowsPath } from "./config.js";
+import { logger } from "./logger.js";
+/**
+ * Load and validate a workflow by name.
+ *
+ * Resolution order:
+ * 1. Built-in TypeScript definitions (highest precedence)
+ * 2. External YAML files in the workflows directory
+ *
+ * Returns the validated definition and its normalized (snapshot-ready) form.
+ */
+export function loadWorkflow(name, options) {
+    const resolved = resolveWorkflowRaw(name, options);
+    // Parse through zod schema (applies defaults, validates structure)
+    const parseResult = WorkflowDefinitionSchema.safeParse(resolved.raw);
+    if (!parseResult.success) {
+        throw new WorkflowValidationError(`Schema validation failed for workflow "${name}": ` +
+            parseResult.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "));
+    }
+    const definition = parseResult.data;
+    // Static validation pipeline (2-6b)
+    validateWorkflow(definition, options.validatorRegistry);
+    // Resolve templates (2-7a)
+    const templates = resolveAllTemplates(definition.stages, options.templatesRoot);
+    // Normalize (2-10a)
+    const normalized = normalizeForSnapshot(definition, templates);
+    return {
+        definition,
+        normalized,
+        source: resolved.source,
+        sourcePath: resolved.sourcePath,
+    };
+}
+/**
+ * Resolve a raw workflow definition object by name.
+ * Built-in TypeScript definitions take precedence over YAML files.
+ */
+function resolveWorkflowRaw(name, options) {
+    // 1. Check built-in definitions first
+    const builtins = getBuiltinWorkflows();
+    const builtin = builtins.get(name);
+    // 2. Check YAML files in the workflows directory
+    const yamlWorkflows = discoverYamlWorkflows(options.workflowsPath);
+    const yamlRaw = yamlWorkflows.get(name);
+    if (builtin != null) {
+        // Warn if a builtin shadows a YAML file with the same name
+        if (yamlRaw != null) {
+            logger.warn({ name, yaml_path: yamlRaw.filePath }, "built-in workflow shadows YAML file with same name");
+        }
+        return { raw: builtin, source: "builtin" };
+    }
+    if (yamlRaw != null) {
+        return { raw: yamlRaw.raw, source: "yaml", sourcePath: yamlRaw.filePath };
+    }
+    // Collect all available names for the error message
+    const allNames = new Set([...builtins.keys(), ...yamlWorkflows.keys()]);
+    throw new WorkflowValidationError(`Unknown workflow: "${name}". Available: ${[...allNames].sort().join(", ")}`);
+}
+/**
+ * List all available workflows (built-in + YAML).
+ * Built-in definitions take precedence over same-named YAML files.
+ * No live child required.
+ *
+ * @param workflowsPath - Optional absolute path to workflows directory for YAML discovery
+ */
+export function listWorkflows(workflowsPath) {
+    const catalog = listWorkflowCatalog(workflowsPath);
+    return new Map([...catalog.entries()].map(([name, entry]) => [name, entry.definition]));
+}
+/**
+ * List workflow definitions with source metadata.
+ * Built-in definitions take precedence over same-named YAML files.
+ */
+export function listWorkflowCatalog(workflowsPath) {
+    const catalog = new Map();
+    // 1. Load YAML workflows first (lower precedence)
+    const yamlWorkflows = discoverYamlWorkflows(workflowsPath);
+    for (const [name, entry] of yamlWorkflows) {
+        const raw = entry.raw;
+        const parseResult = WorkflowDefinitionSchema.safeParse(raw);
+        if (parseResult.success) {
+            catalog.set(name, {
+                definition: parseResult.data,
+                source: "yaml",
+                path: entry.filePath,
+                shadowedYaml: false,
+            });
+        }
+        else {
+            logger.warn({ name, errors: parseResult.error.issues }, "Skipping invalid YAML workflow");
+        }
+    }
+    // 2. Overlay built-in definitions (higher precedence — overwrites same-named YAML)
+    const builtins = getBuiltinWorkflows();
+    for (const [name, raw] of builtins) {
+        const parseResult = WorkflowDefinitionSchema.safeParse(raw);
+        if (parseResult.success) {
+            catalog.set(name, {
+                definition: parseResult.data,
+                source: "builtin",
+                shadowedYaml: yamlWorkflows.has(name),
+            });
+        }
+    }
+    return catalog;
+}
+// ---------------------------------------------------------------------------
+// 7-3: YAML Workflow Discovery
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the workflows directory path.
+ * Uses explicit path if provided, otherwise falls back to config/env.
+ * Resolves relative paths against the package root (dirname of this file → src/ → package root).
+ */
+function resolveWorkflowsDir(explicitPath) {
+    const raw = explicitPath ?? getWorkflowsPath();
+    if (raw.startsWith("/")) {
+        return raw;
+    }
+    // Resolve relative to the package root (two levels up from dist/src/)
+    const packageRoot = resolve(import.meta.dirname, "..");
+    return resolve(packageRoot, raw);
+}
+/**
+ * Discover workflow definitions from YAML files in the workflows directory.
+ * Returns a Map from workflow name (derived from YAML `name` field) to raw parsed object.
+ * Invalid YAML files are logged and skipped.
+ */
+function discoverYamlWorkflows(explicitPath) {
+    const result = new Map();
+    const dir = resolveWorkflowsDir(explicitPath);
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        // Directory doesn't exist or isn't readable — no YAML workflows
+        return result;
+    }
+    for (const entry of entries) {
+        const ext = extname(entry);
+        if (ext !== ".yaml" && ext !== ".yml")
+            continue;
+        const filePath = resolve(dir, entry);
+        try {
+            const content = readFileSync(filePath, "utf-8");
+            const parsed = parseYaml(content);
+            if (parsed == null || typeof parsed !== "object") {
+                logger.warn({ file: filePath }, "YAML workflow file did not parse to an object, skipping");
+                continue;
+            }
+            const obj = parsed;
+            const name = obj["name"];
+            if (typeof name !== "string" || name === "") {
+                logger.warn({ file: filePath }, "YAML workflow file missing 'name' field, skipping");
+                continue;
+            }
+            if (result.has(name)) {
+                logger.warn({ file: filePath, name }, "Duplicate YAML workflow name, keeping first occurrence");
+                continue;
+            }
+            result.set(name, { raw: parsed, filePath });
+        }
+        catch (err) {
+            logger.warn({ file: filePath, error: String(err) }, "Failed to parse YAML workflow file");
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// 2-6b: Static Validation Pipeline
+// ---------------------------------------------------------------------------
+/**
+ * Validate a parsed workflow definition.
+ * All checks are static — no live child required.
+ */
+function validateWorkflow(def, validatorRegistry) {
+    validateUniqueStageIds(def);
+    validateUniqueCallIdsPerStage(def);
+    validateNonEmptyStages(def);
+    validateFinalStage(def);
+    validateContextFromReferences(def);
+    validateNoDuplicateContextFromRefs(def);
+    validateContextProducerContract(def, validatorRegistry);
+    validateNoSideEffects(def);
+}
+/** Unique stage IDs across the workflow. */
+function validateUniqueStageIds(def) {
+    const seen = new Set();
+    for (const stage of def.stages) {
+        if (seen.has(stage.id)) {
+            throw new WorkflowValidationError(`Duplicate stage ID: "${stage.id}"`);
+        }
+        seen.add(stage.id);
+    }
+}
+/** Unique call IDs within each stage. */
+function validateUniqueCallIdsPerStage(def) {
+    for (const stage of def.stages) {
+        const seen = new Set();
+        for (const call of stage.calls) {
+            if (seen.has(call.id)) {
+                throw new WorkflowValidationError(`Duplicate call ID "${call.id}" in stage "${stage.id}"`);
+            }
+            seen.add(call.id);
+        }
+    }
+}
+/** Non-empty stages. */
+function validateNonEmptyStages(def) {
+    for (const stage of def.stages) {
+        if (stage.calls.length === 0) {
+            throw new WorkflowValidationError(`Stage "${stage.id}" has no calls`);
+        }
+    }
+}
+/** Final stage must have exactly one call. */
+function validateFinalStage(def) {
+    const lastStage = def.stages[def.stages.length - 1];
+    if (lastStage == null)
+        return; // Already caught by min(1) in schema
+    if (lastStage.calls.length !== 1) {
+        throw new WorkflowValidationError(`Final stage "${lastStage.id}" must have exactly one call, ` +
+            `got ${String(lastStage.calls.length)}`);
+    }
+}
+/**
+ * context_from references only EARLIER stages (forward-reference rejection).
+ * Accepts "stage_id" (whole stage) or "stage_id.call_id" (specific call).
+ */
+function validateContextFromReferences(def) {
+    const stageOrder = new Map();
+    const callsByStage = new Map();
+    for (let i = 0; i < def.stages.length; i++) {
+        const stage = def.stages[i];
+        stageOrder.set(stage.id, i);
+        const callIds = new Set();
+        for (const call of stage.calls) {
+            callIds.add(call.id);
+        }
+        callsByStage.set(stage.id, callIds);
+    }
+    for (let i = 0; i < def.stages.length; i++) {
+        const stage = def.stages[i];
+        for (const call of stage.calls) {
+            if (call.context_from == null)
+                continue;
+            for (const ref of call.context_from) {
+                const dotIndex = ref.indexOf(".");
+                const refStageId = dotIndex === -1 ? ref : ref.substring(0, dotIndex);
+                const refCallId = dotIndex === -1 ? undefined : ref.substring(dotIndex + 1);
+                const refStageIdx = stageOrder.get(refStageId);
+                if (refStageIdx == null) {
+                    throw new WorkflowValidationError(`context_from reference "${ref}" in call "${call.id}" (stage "${stage.id}") ` +
+                        `references unknown stage "${refStageId}"`);
+                }
+                if (refStageIdx >= i) {
+                    throw new WorkflowValidationError(`Forward reference in context_from: call "${call.id}" (stage "${stage.id}") ` +
+                        `references stage "${refStageId}" which is not earlier`);
+                }
+                if (refCallId != null) {
+                    const refCalls = callsByStage.get(refStageId);
+                    if (refCalls == null || !refCalls.has(refCallId)) {
+                        throw new WorkflowValidationError(`context_from reference "${ref}" in call "${call.id}" (stage "${stage.id}") ` +
+                            `references unknown call "${refCallId}" in stage "${refStageId}"`);
+                    }
+                }
+            }
+        }
+    }
+}
+/** No duplicate context_from refs within a single call. */
+function validateNoDuplicateContextFromRefs(def) {
+    for (const stage of def.stages) {
+        for (const call of stage.calls) {
+            if (call.context_from == null)
+                continue;
+            const seen = new Set();
+            for (const ref of call.context_from) {
+                if (seen.has(ref)) {
+                    throw new WorkflowValidationError(`Duplicate context_from reference "${ref}" in call "${call.id}" (stage "${stage.id}")`);
+                }
+                seen.add(ref);
+            }
+        }
+    }
+}
+/**
+ * 2-8a: Reverse-reference validator-contract enforcement.
+ * Any call referenced by context_from must declare validator_schema_id.
+ */
+function validateContextProducerContract(def, validatorRegistry) {
+    // Collect all referenced call identifiers
+    const referencedCalls = new Set();
+    for (const stage of def.stages) {
+        for (const call of stage.calls) {
+            if (call.context_from == null)
+                continue;
+            for (const ref of call.context_from) {
+                const dotIndex = ref.indexOf(".");
+                if (dotIndex === -1) {
+                    // Whole-stage reference — all calls in that stage are referenced
+                    const refStage = def.stages.find((s) => s.id === ref);
+                    if (refStage != null) {
+                        for (const refCall of refStage.calls) {
+                            referencedCalls.add(`${ref}.${refCall.id}`);
+                        }
+                    }
+                }
+                else {
+                    referencedCalls.add(ref);
+                }
+            }
+        }
+    }
+    // Validate each referenced call
+    for (const ref of referencedCalls) {
+        const dotIndex = ref.indexOf(".");
+        const stageId = ref.substring(0, dotIndex);
+        const callId = ref.substring(dotIndex + 1);
+        const stage = def.stages.find((s) => s.id === stageId);
+        if (stage == null)
+            continue; // Already caught by context_from validation
+        const call = stage.calls.find((c) => c.id === callId);
+        if (call == null)
+            continue;
+        if (call.validator_schema_id == null) {
+            throw new WorkflowValidationError(`Call "${callId}" in stage "${stageId}" is referenced by context_from ` +
+                `but does not declare validator_schema_id — required for context-producing calls`);
+        }
+        if (!validatorRegistry.has(call.validator_schema_id)) {
+            throw new WorkflowValidationError(`Call "${callId}" in stage "${stageId}" declares validator_schema_id ` +
+                `"${call.validator_schema_id}" which is not registered. ` +
+                `Available: ${validatorRegistry.ids().join(", ")}`);
+        }
+    }
+}
+/**
+ * 2-6b: Side-effecting call rejection.
+ * v1 is read-only — any call intended for side effects is a load-time validation error.
+ * Currently this checks for known side-effect indicators; extend as needed.
+ */
+function validateNoSideEffects(_def) {
+    // v1: no side-effect indicators are defined in the schema yet.
+    // This is a placeholder for future extension (e.g., a `side_effects: true` flag).
+    // All v1 workflows are treated as read-only.
+}
+//# sourceMappingURL=loader.js.map