melchizedek-agents 0.9.0 → 0.9.3

package/dist/lib/compile.d.ts

@@ -0,0 +1,64 @@
+/**
+ * lib/compile.ts — the one YAML → ADK agent-graph compiler.
+ *
+ * WHY this file exists:
+ *   The A2A server carried this logic as two closures inside its executor,
+ *   and the observatory (observatory/, the eval harness) needs to run the
+ *   EXACT graph production runs — same subagent wiring, same tool
+ *   resolution, same generateContentConfig merge, same nested
+ *   `yaml_reference` handling. A second copy would have been a second place
+ *   for the two to drift, which is how toolRegistry.ts came to exist.
+ *   So the compiler moved here and both callers import it.
+ *
+ * What it does NOT own: model resolution and nested-config loading. Both are
+ * injected, because the two callers differ precisely there:
+ *   - the A2A server resolves `model` to a provider INSTANCE carrying the
+ *     caller's BYOK key (lib/models/registry.ts resolveModel);
+ *   - the observatory passes the model id through as a string (the
+ *     LLMRegistry routes it) and loads nested syndicates with its
+ *     per-variant overrides already applied.
+ *
+ * ── Two orchestration methods, one compiler ───────────────────────────────
+ * DELEGATE (no `dispatch:` block): every subagent becomes an AgentTool on
+ * the orchestrator. PLAN-DISPATCH (`dispatch:` present): the orchestrator
+ * is compiled WITHOUT subagent tools — it is a pure classifier — and the
+ * caller runs `compileSubagent(route)` directly for the chosen route. Both
+ * paths build subagents through the same function, so the agent a route
+ * dispatches to is identical to the one DELEGATE would have wrapped.
+ * Contract and rationale: lib/dispatch.ts.
+ */
+import { LlmAgent } from '@google/adk';
+import type { BaseLlm } from '@google/adk';
+import type { SubagentYamlConfig, SyndicateYamlConfig } from './loadSyndicate.ts';
+export interface CompileOptions {
+    /**
+     * Turns the YAML `model` string into what LlmAgent receives. Default:
+     * identity — the string goes straight to ADK's LLMRegistry, which needs
+     * `registerAvailableProviders()` to have run (lib/models/registry.ts).
+     * The A2A server substitutes a BYOK instance factory here.
+     */
+    resolveModel?: (model: string | undefined) => string | BaseLlm | undefined;
+    /**
+     * Loads a nested `yaml_reference:` syndicate. Default: `loadSyndicate(ref)`
+     * with no bindings — the same call the server makes. The observatory wraps
+     * this to apply its variant overrides to nested syndicates too.
+     */
+    loadNested?: (ref: string) => SyndicateYamlConfig;
+    /** Called once per YAML tool name that no registry entry matches. */
+    onUnknownTool?: (name: string) => void;
+    /** Progress/diagnostic line sink (nested loads, MCP discovery). */
+    log?: (message: string) => void;
+}
+/**
+ * Builds ONE runnable agent from a subagent entry. A `yaml_reference` entry
+ * compiles the nested syndicate's whole graph under this entry's name and
+ * description, so the parent sees one tool (or one route) either way.
+ */
+export declare function compileSubagent(subCfg: SubagentYamlConfig, opts?: CompileOptions): Promise<LlmAgent>;
+/**
+ * Compiles a syndicate's orchestrator. In DELEGATE mode its subagents are
+ * attached as AgentTools; in PLAN-DISPATCH mode it gets none (ADK refuses
+ * outputSchema + AgentTool on one agent — see config/agents/critic.yaml),
+ * and the caller dispatches to `compileSubagent(route)` itself.
+ */
+export declare function compileGraph(config: SyndicateYamlConfig, opts?: CompileOptions, overrideName?: string, overrideDescription?: string): Promise<LlmAgent>;

package/dist/lib/compile.js

@@ -0,0 +1,105 @@
+/**
+ * lib/compile.ts — the one YAML → ADK agent-graph compiler.
+ *
+ * WHY this file exists:
+ *   The A2A server carried this logic as two closures inside its executor,
+ *   and the observatory (observatory/, the eval harness) needs to run the
+ *   EXACT graph production runs — same subagent wiring, same tool
+ *   resolution, same generateContentConfig merge, same nested
+ *   `yaml_reference` handling. A second copy would have been a second place
+ *   for the two to drift, which is how toolRegistry.ts came to exist.
+ *   So the compiler moved here and both callers import it.
+ *
+ * What it does NOT own: model resolution and nested-config loading. Both are
+ * injected, because the two callers differ precisely there:
+ *   - the A2A server resolves `model` to a provider INSTANCE carrying the
+ *     caller's BYOK key (lib/models/registry.ts resolveModel);
+ *   - the observatory passes the model id through as a string (the
+ *     LLMRegistry routes it) and loads nested syndicates with its
+ *     per-variant overrides already applied.
+ *
+ * ── Two orchestration methods, one compiler ───────────────────────────────
+ * DELEGATE (no `dispatch:` block): every subagent becomes an AgentTool on
+ * the orchestrator. PLAN-DISPATCH (`dispatch:` present): the orchestrator
+ * is compiled WITHOUT subagent tools — it is a pure classifier — and the
+ * caller runs `compileSubagent(route)` directly for the chosen route. Both
+ * paths build subagents through the same function, so the agent a route
+ * dispatches to is identical to the one DELEGATE would have wrapped.
+ * Contract and rationale: lib/dispatch.ts.
+ */
+import { AgentTool, LlmAgent } from '@google/adk';
+import { isDispatchSyndicate } from "./dispatch.js";
+import { loadSyndicate } from "./loadSyndicate.js";
+import { resolveTools as resolveNamedTools } from "./toolRegistry.js";
+import { createMcpTools } from "./tools/mcpToolFactory.js";
+/** generateContentConfig as every entrypoint has always sent it to ADK. */
+function withServerSideToolInvocations(generateContentConfig) {
+    const cfg = (generateContentConfig ?? {});
+    return {
+        ...cfg,
+        toolConfig: {
+            ...(cfg.toolConfig ?? {}),
+            includeServerSideToolInvocations: true,
+        },
+    };
+}
+async function resolveAgentTools(toolNames, mcpServerUrl, opts) {
+    const tools = resolveNamedTools(toolNames, opts.onUnknownTool);
+    if (mcpServerUrl) {
+        opts.log?.(`Loading MCP tools: ${mcpServerUrl}`);
+        const mcpTools = await createMcpTools(mcpServerUrl);
+        for (const mcpTool of mcpTools) {
+            if (!tools.some((t) => t.name === mcpTool.name))
+                tools.push(mcpTool);
+        }
+    }
+    return tools;
+}
+/**
+ * Builds ONE runnable agent from a subagent entry. A `yaml_reference` entry
+ * compiles the nested syndicate's whole graph under this entry's name and
+ * description, so the parent sees one tool (or one route) either way.
+ */
+export async function compileSubagent(subCfg, opts = {}) {
+    if (subCfg.yaml_reference) {
+        opts.log?.(`Loading nested syndicate: ${subCfg.yaml_reference}`);
+        const nested = (opts.loadNested ?? loadSyndicate)(subCfg.yaml_reference);
+        return compileGraph(nested, opts, subCfg.name, subCfg.description);
+    }
+    const tools = await resolveAgentTools(subCfg.tools, subCfg.mcp_server_url, opts);
+    const resolveModel = opts.resolveModel ?? ((m) => m);
+    return new LlmAgent({
+        name: subCfg.name,
+        description: subCfg.description,
+        model: resolveModel(subCfg.model),
+        instruction: subCfg.instruction,
+        tools: tools.length > 0 ? tools : undefined,
+        outputSchema: subCfg.outputSchema,
+        generateContentConfig: withServerSideToolInvocations(subCfg.generateContentConfig),
+    });
+}
+/**
+ * Compiles a syndicate's orchestrator. In DELEGATE mode its subagents are
+ * attached as AgentTools; in PLAN-DISPATCH mode it gets none (ADK refuses
+ * outputSchema + AgentTool on one agent — see config/agents/critic.yaml),
+ * and the caller dispatches to `compileSubagent(route)` itself.
+ */
+export async function compileGraph(config, opts = {}, overrideName, overrideDescription) {
+    const compiledTools = isDispatchSyndicate(config)
+        ? []
+        : await Promise.all((config.subagents ?? []).map(async (subCfg) => new AgentTool({ agent: await compileSubagent(subCfg, opts) })));
+    // Orchestrator tools are registry names only — no entrypoint has ever
+    // attached an MCP server to an orchestrator, and this compiler preserves
+    // that exactly rather than widening the contract in passing.
+    compiledTools.push(...(await resolveAgentTools(config.orchestrator.tools, undefined, opts)));
+    const resolveModel = opts.resolveModel ?? ((m) => m);
+    return new LlmAgent({
+        name: overrideName || config.orchestrator.name,
+        description: overrideDescription || config.orchestrator.description,
+        model: resolveModel(config.orchestrator.model),
+        instruction: config.orchestrator.instruction,
+        tools: compiledTools.length > 0 ? compiledTools : undefined,
+        outputSchema: config.orchestrator.outputSchema,
+        generateContentConfig: withServerSideToolInvocations(config.orchestrator.generateContentConfig),
+    });
+}

package/dist/lib/models/claudeLlm.js

@@ -50,6 +50,8 @@ import { traceLlmGeneration, setLlmSpanAttribute, } from "../observability/trace
 import { wantsWebSearch, isWebSearchSentinel, } from "../tools/webSearchTool.js";
 import { toLowercaseJsonSchema } from "./schemaNormalize.js";
 /** Anthropic's minimum extended-thinking budget. */
+/** Name of the synthetic tool that carries an ADK outputSchema answer. */
+const STRUCTURED_OUTPUT_TOOL = 'structured_output';
 const MIN_THINKING_BUDGET = 1024;
 // ── Request building (exported for offline tests) ────────────────────────────
 /** ADK toolsDict → Anthropic tool definitions (lowercase schemas; the
@@ -199,12 +201,30 @@ export class ClaudeLlm extends BaseLlm {
             // Anthropic requires max_tokens to exceed the thinking budget.
             maxTokens = Math.max(maxTokens, budget + 2048);
         }
+        // ── Structured output (ADK outputSchema → forced tool use) ──────────────
+        // The Messages API has no response_format. Left to prose, Claude returns
+        // JSON whose KEYS drift from the schema ("grade" for "correctness"), which
+        // silently breaks any consumer that reads fields by name — the
+        // observatory's rubric judges first of all. A tool whose input_schema IS
+        // the output schema, with tool_choice forcing it, makes the API validate
+        // the shape; finalResponse() turns the tool_use block back into text.
+        // Forced tool_choice is incompatible with extended thinking, so with a
+        // thinking budget the tool is offered under 'auto' instead.
+        const structuredTool = cfg.responseSchema
+            ? {
+                name: STRUCTURED_OUTPUT_TOOL,
+                description: 'Return the final answer as a JSON object matching this schema. Call this exactly once.',
+                input_schema: toLowercaseJsonSchema(cfg.responseSchema),
+            }
+            : undefined;
+        const allTools = structuredTool ? [...anthropicTools, structuredTool] : anthropicTools;
         const requestBase = {
             model: this.model,
             max_tokens: maxTokens,
             system: systemParts.join('\n\n') || undefined,
             messages,
-            tools: anthropicTools.length > 0 ? anthropicTools : undefined,
+            tools: allTools.length > 0 ? allTools : undefined,
+            ...(structuredTool && !thinking ? { tool_choice: { type: 'tool', name: STRUCTURED_OUTPUT_TOOL } } : {}),
             ...(thinking ? { thinking } : {}),
         };
         // ── Call Anthropic API ────────────────────────────────────────────────────
@@ -271,6 +291,10 @@ export class ClaudeLlm extends BaseLlm {
             if (block.type === 'text' && includeText) {
                 parts.push({ text: block.text });
             }
+            else if (block.type === 'tool_use' && block.name === STRUCTURED_OUTPUT_TOOL) {
+                // The schema-validated answer, as the JSON text every consumer expects.
+                parts.push({ text: JSON.stringify(block.input ?? {}) });
+            }
             else if (block.type === 'tool_use') {
                 parts.push({
                     functionCall: { name: block.name, args: block.input, id: block.id },

package/dist/lib/models/gptLlm.js

@@ -48,7 +48,7 @@ import { wantsWebSearch, isWebSearchSentinel, xaiWebSearchParamsFromEnv, } from
 import { wantsXSearch, isXSearchSentinel, xSearchParamsFromEnv, } from "../tools/xSearchTool.js";
 import { wantsCollectionsSearch, isCollectionsSearchSentinel, collectionIdsFromEnv, collectionsMaxResultsFromEnv, } from "../tools/collectionsSearchTool.js";
 import { providerForModel } from "./providerMap.js";
-import { toLowercaseJsonSchema } from "./schemaNormalize.js";
+import { toLowercaseJsonSchema, toStrictJsonSchema } from "./schemaNormalize.js";
 /** Reasoning-capable ids: o-series and the gpt-5 family. The reasoning
  *  param is also dropped and retried once on a 400, so a miss here only
  *  costs one extra round trip. */
@@ -303,7 +303,10 @@ export class GptLlm extends BaseLlm {
                         format: {
                             type: 'json_schema',
                             name: 'response',
-                            schema: toLowercaseJsonSchema(cfg.responseSchema),
+                            // Strict: the API enforces the exact property names, so a
+                            // judge rubric's fields arrive as declared, never renamed.
+                            strict: true,
+                            schema: toStrictJsonSchema(cfg.responseSchema),
                         },
                     },
                 }

package/dist/lib/models/ollamaLlm.d.ts

@@ -75,6 +75,8 @@
 import type { LlmRequest, LlmResponse } from '@google/adk';
 import { OpenAiCompatibleLlm } from './openAiCompatibleLlm.ts';
 export declare class OllamaLlm extends OpenAiCompatibleLlm {
+    /** Ollama's OpenAI-compatible endpoint takes json_object, not json_schema. */
+    protected supportsJsonSchemaFormat(): boolean;
     /**
      * Model ids namespaced "ollama/<model>" route here after registration,
      * e.g. model: "ollama/qwen3:8b" in a syndicate YAML.

package/dist/lib/models/ollamaLlm.js

@@ -77,6 +77,10 @@ import { OpenAiCompatibleLlm } from "./openAiCompatibleLlm.js";
 const DEFAULT_BASE_URL = 'http://localhost:11434/v1';
 // ── OllamaLlm ─────────────────────────────────────────────────────────────────
 export class OllamaLlm extends OpenAiCompatibleLlm {
+    /** Ollama's OpenAI-compatible endpoint takes json_object, not json_schema. */
+    supportsJsonSchemaFormat() {
+        return false;
+    }
     /**
      * Model ids namespaced "ollama/<model>" route here after registration,
      * e.g. model: "ollama/qwen3:8b" in a syndicate YAML.

package/dist/lib/models/openAiCompatibleLlm.d.ts

@@ -77,6 +77,8 @@ export declare abstract class OpenAiCompatibleLlm extends BaseLlm {
     /** Model id as the wire expects it (e.g. strip the "ollama/" namespace). */
     protected wireModelName(): string;
     /** Provider-specific request body fields (merged last). */
+    /** Whether the endpoint accepts response_format json_schema (strict). */
+    protected supportsJsonSchemaFormat(): boolean;
     protected extraBodyFields(_llmRequest: LlmRequest): Record<string, unknown>;
     /**
      * Body fields enabling the provider's NATIVE web search, or null when the

package/dist/lib/models/openAiCompatibleLlm.js

@@ -30,7 +30,7 @@
 import { BaseLlm } from '@google/adk';
 import { traceLlmGeneration, setLlmSpanAttribute, } from "../observability/tracer.js";
 import { wantsWebSearch, isWebSearchSentinel, } from "../tools/webSearchTool.js";
-import { toLowercaseJsonSchema } from "./schemaNormalize.js";
+import { toLowercaseJsonSchema, toStrictJsonSchema } from "./schemaNormalize.js";
 /** Splits "<think>…</think>" scratchpad from the reply. */
 export function splitThinkBlocks(text) {
     const blocks = [];
@@ -50,6 +50,10 @@ export class OpenAiCompatibleLlm extends BaseLlm {
         return this.model;
     }
     /** Provider-specific request body fields (merged last). */
+    /** Whether the endpoint accepts response_format json_schema (strict). */
+    supportsJsonSchemaFormat() {
+        return true;
+    }
     extraBodyFields(_llmRequest) {
         return {};
     }
@@ -115,10 +119,15 @@ export class OpenAiCompatibleLlm extends BaseLlm {
                 ? { max_tokens: cfg.maxOutputTokens }
                 : {}),
             ...(openAiTools.length > 0 ? { tools: openAiTools } : {}),
-            // critic-style structured output: responseMimeType JSON → json mode
-            ...(cfg.responseMimeType === 'application/json'
-                ? { response_format: { type: 'json_object' } }
-                : {}),
+            // Structured output: an ADK outputSchema becomes a strict json_schema
+            // response_format where the endpoint supports it (xAI does; Ollama's
+            // OpenAI-compatible endpoint does not, see supportsJsonSchemaFormat),
+            // else plain JSON mode.
+            ...(cfg.responseSchema && this.supportsJsonSchemaFormat()
+                ? { response_format: { type: 'json_schema', json_schema: { name: 'response', strict: true, schema: toStrictJsonSchema(cfg.responseSchema) } } }
+                : cfg.responseMimeType === 'application/json' || cfg.responseSchema
+                    ? { response_format: { type: 'json_object' } }
+                    : {}),
             ...this.extraBodyFields(llmRequest),
         };
         // web_search: enable the provider's native search, or omit with a warning.

package/dist/lib/models/schemaNormalize.d.ts

@@ -20,3 +20,12 @@
  * Never mutates the input — a Gemini agent may hold the same tool object.
  */
 export declare function toLowercaseJsonSchema(schema: unknown): Record<string, unknown>;
+/**
+ * The lowercase schema in the shape OpenAI-style "strict" structured output
+ * demands: every object node carries `additionalProperties: false` and lists
+ * ALL of its properties as required. Optional fields are expressed by the
+ * model emitting a null/empty value, not by omission — that is the strict
+ * contract, and it is what makes a judge's rubric fields arrive under the
+ * names the harness expects rather than improvised ones.
+ */
+export declare function toStrictJsonSchema(schema: unknown): Record<string, unknown>;

package/dist/lib/models/schemaNormalize.js

@@ -56,3 +56,37 @@ function normalizeNode(node) {
     }
     return out;
 }
+/**
+ * The lowercase schema in the shape OpenAI-style "strict" structured output
+ * demands: every object node carries `additionalProperties: false` and lists
+ * ALL of its properties as required. Optional fields are expressed by the
+ * model emitting a null/empty value, not by omission — that is the strict
+ * contract, and it is what makes a judge's rubric fields arrive under the
+ * names the harness expects rather than improvised ones.
+ */
+export function toStrictJsonSchema(schema) {
+    return strictNode(toLowercaseJsonSchema(schema));
+}
+function strictNode(node) {
+    if (Array.isArray(node))
+        return node.map(strictNode);
+    if (!node || typeof node !== 'object')
+        return node;
+    const out = { ...node };
+    const type = out.type;
+    const isObject = type === 'object' || (Array.isArray(type) && type.includes('object')) || isPlainObject(out.properties);
+    if (isObject && isPlainObject(out.properties)) {
+        const props = {};
+        for (const [k, v] of Object.entries(out.properties))
+            props[k] = strictNode(v);
+        out.properties = props;
+        out.required = Object.keys(props);
+        out.additionalProperties = false;
+    }
+    if (out.items !== undefined)
+        out.items = strictNode(out.items);
+    return out;
+}
+function isPlainObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}

package/dist/lib/observability/embeddings.d.ts

@@ -0,0 +1,21 @@
+/**
+ * lib/observability/embeddings.ts — embeddings for ledger search.
+ *
+ * The same model and dimensionality as long-term memory (lib/config.ts), so
+ * a query embedded here is comparable to a turn embedded by
+ * `npm run telemetry:embed`, and the `match_turns` RPC (db/telemetry.sql)
+ * compares apples to apples. Kept out of the exporter on purpose: an API
+ * call per turn would put inference on the export path; a job embeds in
+ * batches after the fact.
+ */
+import { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL } from '../config.ts';
+export interface EmbedOptions {
+    apiKey?: string;
+    /** Characters kept per text (long answers are truncated, not skipped). */
+    maxChars?: number;
+}
+/** Embeds each text; a failed text yields an empty vector rather than a throw. */
+export declare function embedTexts(texts: string[], options?: EmbedOptions): Promise<number[][]>;
+/** The text a turn is embedded by: the question and the answer, in that order. */
+export declare function turnEmbeddingText(input: string | null | undefined, output: string | null | undefined): string;
+export { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL };

package/dist/lib/observability/embeddings.js

@@ -0,0 +1,47 @@
+/**
+ * lib/observability/embeddings.ts — embeddings for ledger search.
+ *
+ * The same model and dimensionality as long-term memory (lib/config.ts), so
+ * a query embedded here is comparable to a turn embedded by
+ * `npm run telemetry:embed`, and the `match_turns` RPC (db/telemetry.sql)
+ * compares apples to apples. Kept out of the exporter on purpose: an API
+ * call per turn would put inference on the export path; a job embeds in
+ * batches after the fact.
+ */
+import { GoogleGenAI } from '@google/genai';
+import { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL } from "../config.js";
+const MAX_CHARS = 8_000;
+/** Embeds each text; a failed text yields an empty vector rather than a throw. */
+export async function embedTexts(texts, options = {}) {
+    const apiKey = options.apiKey ?? process.env.GOOGLE_GENAI_API_KEY ?? process.env.GEMINI_API_KEY;
+    if (!apiKey)
+        throw new Error('GOOGLE_GENAI_API_KEY is required for embeddings');
+    const genai = new GoogleGenAI({ apiKey });
+    const limit = options.maxChars ?? MAX_CHARS;
+    const out = [];
+    for (const text of texts) {
+        const clipped = (text ?? '').slice(0, limit);
+        if (!clipped.trim()) {
+            out.push([]);
+            continue;
+        }
+        try {
+            const response = await genai.models.embedContent({
+                model: EMBEDDING_MODEL,
+                contents: clipped,
+                config: { outputDimensionality: EMBEDDING_DIMENSIONS },
+            });
+            out.push(response.embeddings?.[0]?.values ?? []);
+        }
+        catch (err) {
+            console.warn(`[embeddings] failed: ${err instanceof Error ? err.message : String(err)}`);
+            out.push([]);
+        }
+    }
+    return out;
+}
+/** The text a turn is embedded by: the question and the answer, in that order. */
+export function turnEmbeddingText(input, output) {
+    return `${(input ?? '').trim()}\n\n${(output ?? '').trim()}`.trim();
+}
+export { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL };

package/dist/lib/observability/lineage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * lib/observability/lineage.ts — provenance stamps for the ledger.
+ *
+ * A stored output is evidence only if you know exactly what produced it.
+ * Every turn row carries two stamps computed here:
+ *
+ *   config_hash     SHA-256 (first 16 hex) of the RESOLVED syndicate config
+ *                   with every nested `yaml_reference` inlined — the exact
+ *                   prompts, models, tools and generation settings that ran.
+ *                   Two deployments serving "the same" syndicate with a
+ *                   drifted registry row or a stale file produce different
+ *                   hashes, which is the first time that drift is visible in
+ *                   stored data. Eval runs hash the overridden config, so a
+ *                   variant's rows are distinguishable from production's.
+ *   engine_version  package version plus the git commit (or the platform's
+ *                   SOURCE_VERSION / HEROKU_SLUG_COMMIT), so a behaviour
+ *                   change can be pinned to a deploy.
+ *
+ * Both are deterministic and cheap; neither touches the network.
+ */
+import type { SyndicateYamlConfig } from '../loadSyndicate.ts';
+/** Schema version stamped on every ledger row (adk_turns / adk_payloads). */
+export declare const TELEMETRY_SCHEMA_VERSION = 2;
+/** JSON with object keys sorted at every depth — stable across reloads. */
+export declare function stableStringify(value: unknown): string;
+/** The config with every `yaml_reference` replaced by the loaded syndicate. */
+export declare function inlineReferences(config: SyndicateYamlConfig, loadNested: (ref: string) => SyndicateYamlConfig, seen?: Set<string>): Record<string, unknown>;
+/**
+ * Hash of the fully resolved config. `loadNested` is the same loader the
+ * caller compiles with (the server's plain loadSyndicate; the observatory's
+ * override-applying loader), so the hash describes what actually ran.
+ */
+export declare function configDigest(config: SyndicateYamlConfig, loadNested: (ref: string) => SyndicateYamlConfig): string;
+/** "<package version>+<commit>" — commit from the platform env or git, else "local". */
+export declare function engineVersion(): string;

package/dist/lib/observability/lineage.js

@@ -0,0 +1,96 @@
+/**
+ * lib/observability/lineage.ts — provenance stamps for the ledger.
+ *
+ * A stored output is evidence only if you know exactly what produced it.
+ * Every turn row carries two stamps computed here:
+ *
+ *   config_hash     SHA-256 (first 16 hex) of the RESOLVED syndicate config
+ *                   with every nested `yaml_reference` inlined — the exact
+ *                   prompts, models, tools and generation settings that ran.
+ *                   Two deployments serving "the same" syndicate with a
+ *                   drifted registry row or a stale file produce different
+ *                   hashes, which is the first time that drift is visible in
+ *                   stored data. Eval runs hash the overridden config, so a
+ *                   variant's rows are distinguishable from production's.
+ *   engine_version  package version plus the git commit (or the platform's
+ *                   SOURCE_VERSION / HEROKU_SLUG_COMMIT), so a behaviour
+ *                   change can be pinned to a deploy.
+ *
+ * Both are deterministic and cheap; neither touches the network.
+ */
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Schema version stamped on every ledger row (adk_turns / adk_payloads). */
+export const TELEMETRY_SCHEMA_VERSION = 2;
+/** JSON with object keys sorted at every depth — stable across reloads. */
+export function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const obj = value;
+    const keys = Object.keys(obj)
+        .filter((k) => obj[k] !== undefined)
+        .sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`;
+}
+/** The config with every `yaml_reference` replaced by the loaded syndicate. */
+export function inlineReferences(config, loadNested, seen = new Set()) {
+    return {
+        ...config,
+        subagents: (config.subagents ?? []).map((sub) => {
+            if (!sub.yaml_reference || seen.has(sub.yaml_reference))
+                return sub;
+            const next = new Set(seen);
+            next.add(sub.yaml_reference);
+            let nested;
+            try {
+                nested = inlineReferences(loadNested(sub.yaml_reference), loadNested, next);
+            }
+            catch (err) {
+                nested = { unresolved: sub.yaml_reference, error: err instanceof Error ? err.message : String(err) };
+            }
+            return { ...sub, resolved_reference: nested };
+        }),
+    };
+}
+/**
+ * Hash of the fully resolved config. `loadNested` is the same loader the
+ * caller compiles with (the server's plain loadSyndicate; the observatory's
+ * override-applying loader), so the hash describes what actually ran.
+ */
+export function configDigest(config, loadNested) {
+    const resolved = inlineReferences(config, loadNested);
+    return createHash('sha256').update(stableStringify(resolved)).digest('hex').slice(0, 16);
+}
+let cachedEngineVersion;
+/** "<package version>+<commit>" — commit from the platform env or git, else "local". */
+export function engineVersion() {
+    if (cachedEngineVersion)
+        return cachedEngineVersion;
+    let pkgVersion = '0.0.0';
+    try {
+        const pkgPath = join(process.cwd(), 'package.json');
+        if (existsSync(pkgPath)) {
+            pkgVersion = String(JSON.parse(readFileSync(pkgPath, 'utf-8')).version ?? pkgVersion);
+        }
+    }
+    catch {
+        /* no package.json in cwd — version stays 0.0.0 */
+    }
+    let commit = process.env.SOURCE_VERSION ?? process.env.HEROKU_SLUG_COMMIT ?? process.env.GIT_COMMIT ?? '';
+    if (!commit) {
+        try {
+            commit = execSync('git rev-parse --short HEAD', { stdio: ['ignore', 'pipe', 'ignore'] })
+                .toString()
+                .trim();
+        }
+        catch {
+            commit = 'local';
+        }
+    }
+    cachedEngineVersion = `${pkgVersion}+${commit.slice(0, 12)}`;
+    return cachedEngineVersion;
+}