@fusionkit/protocol 0.1.0

package/dist/test/protocol.test.js

@@ -0,0 +1,240 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { appendEvent, verifyChain } from "../chain.js";
+import { contractHash, signContract } from "../contract.js";
+import { canonicalize } from "../jcs.js";
+import { hashCanonical } from "../hash.js";
+import { generateEd25519KeyPair, keyIdFromPublicPem, signData, verifyData } from "../keys.js";
+import { signReceipt, verifyReceiptBundle, verifyRunnerReceipt } from "../receipt.js";
+import { buildReceiptStory } from "../receipt-story.js";
+import { AGENT_KINDS, isAgentKind, isTerminalStatus, parseSecretName, parseWorkspaceManifestPath, RUN_STATUSES, SESSION_ISOLATIONS } from "../index.js";
+test("canonicalize sorts keys and is whitespace-free", () => {
+    const value = { b: 2, a: { d: [1, 2, { z: true, y: null }], c: "x" } };
+    assert.equal(canonicalize(value), '{"a":{"c":"x","d":[1,2,{"y":null,"z":true}]},"b":2}');
+});
+test("canonicalize uses ES number serialization", () => {
+    assert.equal(canonicalize({ n: 1e21 }), '{"n":1e+21}');
+    assert.equal(canonicalize({ n: 0.000001 }), '{"n":0.000001}');
+    assert.equal(canonicalize({ n: 10 }), '{"n":10}');
+    assert.throws(() => canonicalize({ n: Infinity }));
+});
+test("canonicalize is order-insensitive for equal objects", () => {
+    const a = { x: 1, y: [true, "s"] };
+    const b = { y: [true, "s"], x: 1 };
+    assert.equal(hashCanonical(a), hashCanonical(b));
+});
+test("ed25519 sign/verify roundtrip and tamper detection", () => {
+    const keys = generateEd25519KeyPair();
+    const payload = "warrant test payload";
+    const sig = signData(keys.privateKeyPem, payload);
+    assert.equal(verifyData(keys.publicKeyPem, payload, sig), true);
+    assert.equal(verifyData(keys.publicKeyPem, payload + "x", sig), false);
+    const other = generateEd25519KeyPair();
+    assert.equal(verifyData(other.publicKeyPem, payload, sig), false);
+    assert.match(keyIdFromPublicPem(keys.publicKeyPem), /^ed25519:[0-9a-f]{16}$/);
+});
+test("event chain appends and verifies; tampering breaks it", () => {
+    const genesis = hashCanonical({ contract: "fake" });
+    const chain = [];
+    appendEvent(chain, { type: "run.created" }, genesis);
+    appendEvent(chain, { type: "policy.evaluated", decision: "allow", reason: "test" }, genesis);
+    appendEvent(chain, { type: "run.completed" }, genesis);
+    assert.deepEqual(verifyChain(chain, genesis), { ok: true });
+    const tampered = structuredClone(chain);
+    const second = tampered[1];
+    assert.ok(second);
+    second.event = {
+        type: "policy.evaluated",
+        decision: "allow",
+        reason: "rewritten history"
+    };
+    const result = verifyChain(tampered, genesis);
+    assert.equal(result.ok, false);
+    if (!result.ok)
+        assert.equal(result.brokenAtSeq, 1);
+    const dropped = chain.slice(1);
+    const droppedResult = verifyChain(dropped, genesis);
+    assert.equal(droppedResult.ok, false);
+});
+test("protocol vocabulary is canonical and guarded", () => {
+    assert.deepEqual(AGENT_KINDS, ["claude-code", "codex", "pi", "mock", "command"]);
+    assert.deepEqual(SESSION_ISOLATIONS, [
+        "process",
+        "hermetic",
+        "vercel-sandbox"
+    ]);
+    assert.ok(RUN_STATUSES.includes("awaiting_approval"));
+    assert.equal(isAgentKind("command"), true);
+    assert.equal(isAgentKind("shell"), false);
+    assert.equal(isTerminalStatus("completed"), true);
+    assert.equal(isTerminalStatus("running"), false);
+});
+test("protocol validators reject unsafe workspace paths and secret names", () => {
+    assert.equal(parseWorkspaceManifestPath("src/index.ts"), "src/index.ts");
+    assert.throws(() => parseWorkspaceManifestPath("../escape"));
+    assert.throws(() => parseWorkspaceManifestPath("/absolute"));
+    assert.throws(() => parseWorkspaceManifestPath("a/../escape"));
+    assert.equal(parseSecretName("API_TOKEN"), "API_TOKEN");
+    assert.throws(() => parseSecretName("bad-name"));
+});
+function receiptFixture(isolation = "process") {
+    const plane = generateEd25519KeyPair();
+    const runner = generateEd25519KeyPair();
+    const workspace = {
+        version: "warrant.manifest.v1",
+        baseRef: "abc123",
+        bundleHash: "1".repeat(64),
+        untrackedFiles: [],
+        deniedPatterns: [],
+        deniedPaths: []
+    };
+    const contract = signContract({
+        version: "warrant.contract.v1",
+        runId: "run_test",
+        issuedAt: "2026-06-11T00:00:00.000Z",
+        issuer: { keyId: keyIdFromPublicPem(plane.publicKeyPem), role: "plane" },
+        requestedBy: { kind: "human", id: "alice" },
+        agent: { kind: "command" },
+        task: { prompt: "echo hi" },
+        runner: { pool: "default" },
+        workspace,
+        policyHash: "2".repeat(64),
+        secrets: [{ name: "API_TOKEN", scope: "pool:default" }],
+        network: { defaultDeny: true, allowHosts: [] },
+        budget: {},
+        disclosure: "minimal-context",
+        execution: { kind: "shell", script: "echo hi" },
+        expiresAt: "2026-06-11T01:00:00.000Z",
+        signatures: []
+    }, plane.privateKeyPem, plane.publicKeyPem, "plane");
+    const genesis = contractHash(contract);
+    const events = [];
+    appendEvent(events, { type: "run.created" }, genesis);
+    appendEvent(events, { type: "secret.released", name: "API_TOKEN", scope: "pool:default" }, genesis);
+    appendEvent(events, { type: "command.executed", argvHash: "3".repeat(64), exitCode: 0 }, genesis);
+    appendEvent(events, { type: "run.completed" }, genesis);
+    const secretEvent = events.find((event) => event.event.type === "secret.released");
+    assert.ok(secretEvent);
+    const last = events.at(-1);
+    assert.ok(last);
+    const receipt = signReceipt({
+        version: "warrant.receipt.v1",
+        runId: "run_test",
+        contractHash: genesis,
+        runner: {
+            runnerId: "rnr_test",
+            keyId: keyIdFromPublicPem(runner.publicKeyPem),
+            pool: "default",
+            attestationTier: "standard",
+            isolation
+        },
+        startedAt: "2026-06-11T00:00:00.000Z",
+        endedAt: "2026-06-11T00:00:01.000Z",
+        status: "completed",
+        eventsHead: last.hash,
+        eventCount: events.length,
+        workspaceIn: {
+            baseRef: workspace.baseRef,
+            manifestHash: hashCanonical(workspace)
+        },
+        workspaceOut: { diffHash: "", artifactHashes: [] },
+        secretsReleased: [
+            {
+                name: "API_TOKEN",
+                scope: "pool:default",
+                ts: secretEvent.ts
+            }
+        ],
+        networkAccessed: [],
+        modelsUsed: [],
+        boundaryDisclosures: [],
+        signatures: []
+    }, runner.privateKeyPem, runner.publicKeyPem, "runner");
+    return {
+        contract,
+        receipt,
+        events,
+        planePrivateKeyPem: plane.privateKeyPem,
+        planePublicKeyPem: plane.publicKeyPem,
+        runnerPublicKeyPem: runner.publicKeyPem
+    };
+}
+test("verifyRunnerReceipt checks pre-countersign receipt evidence", () => {
+    const fixture = receiptFixture();
+    assert.deepEqual(verifyRunnerReceipt({
+        contract: fixture.contract,
+        receipt: fixture.receipt,
+        events: fixture.events,
+        runnerPublicKeyPem: fixture.runnerPublicKeyPem
+    }), { ok: true, problems: [] });
+    const tampered = structuredClone(fixture.receipt);
+    tampered.eventCount += 1;
+    const result = verifyRunnerReceipt({
+        contract: fixture.contract,
+        receipt: tampered,
+        events: fixture.events,
+        runnerPublicKeyPem: fixture.runnerPublicKeyPem
+    });
+    assert.equal(result.ok, false);
+    assert.ok(result.problems.includes("receipt.eventCount does not match the event chain"));
+    const forgedScope = structuredClone(fixture.receipt);
+    forgedScope.secretsReleased[0] = {
+        ...forgedScope.secretsReleased[0],
+        scope: "pool:other"
+    };
+    const scopeResult = verifyRunnerReceipt({
+        contract: fixture.contract,
+        receipt: forgedScope,
+        events: fixture.events,
+        runnerPublicKeyPem: fixture.runnerPublicKeyPem
+    });
+    assert.equal(scopeResult.ok, false);
+    assert.ok(scopeResult.problems.includes("secretsReleased does not match secret.released events"));
+    const forgedTimestamp = structuredClone(fixture.receipt);
+    forgedTimestamp.secretsReleased[0] = {
+        ...forgedTimestamp.secretsReleased[0],
+        ts: "2026-06-11T00:00:00.999Z"
+    };
+    const timestampResult = verifyRunnerReceipt({
+        contract: fixture.contract,
+        receipt: forgedTimestamp,
+        events: fixture.events,
+        runnerPublicKeyPem: fixture.runnerPublicKeyPem
+    });
+    assert.equal(timestampResult.ok, false);
+    assert.ok(timestampResult.problems.includes("secretsReleased does not match secret.released events"));
+});
+test("receipt story is the canonical CLI/UI summary model", () => {
+    const fixture = receiptFixture();
+    const story = buildReceiptStory({
+        version: "warrant.bundle.v1",
+        contract: fixture.contract,
+        receipt: fixture.receipt,
+        events: fixture.events,
+        keys: {
+            planePublicKeyPem: generateEd25519KeyPair().publicKeyPem,
+            runnerPublicKeyPem: fixture.runnerPublicKeyPem
+        }
+    });
+    assert.equal(story.runId, "run_test");
+    assert.equal(story.status, "completed");
+    assert.equal(story.agent, "command");
+    assert.deepEqual(story.secrets, ["API_TOKEN (pool:default)"]);
+});
+test("vercel-sandbox receipts verify offline and render through receipt story", () => {
+    const fixture = receiptFixture("vercel-sandbox");
+    const receipt = signReceipt(fixture.receipt, fixture.planePrivateKeyPem, fixture.planePublicKeyPem, "plane");
+    const bundle = {
+        version: "warrant.bundle.v1",
+        contract: fixture.contract,
+        receipt,
+        events: fixture.events,
+        keys: {
+            planePublicKeyPem: fixture.planePublicKeyPem,
+            runnerPublicKeyPem: fixture.runnerPublicKeyPem
+        }
+    };
+    assert.deepEqual(verifyReceiptBundle(bundle), { ok: true, problems: [] });
+    const story = buildReceiptStory(bundle);
+    assert.equal(story.isolation, "vercel-sandbox");
+});

package/dist/test/tool-executor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/tool-executor.test.js

@@ -0,0 +1,86 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { evaluateToolPolicy, modelFusionSideEffects, toolArgumentsHash, toolCallKey, toolSideEffectClassFromModelFusion } from "../tool-executor.js";
+import { MODEL_FUSION_SCHEMA_BUNDLE_HASH } from "../model-fusion.js";
+const contract = {
+    executor_id: "exec_demo",
+    mode: "demo_safe",
+    environment_id: "env_local",
+    tool_policy_id: "policy_readonly",
+    allowed_tools: ["read_file", "echo"],
+    side_effects: ["none", "read"],
+    limits: { timeoutMs: 1000, maxOutputBytes: 1024 },
+    timeoutMs: 1000,
+    budget: { maxSpendUsd: 0 },
+    audit_sink: "memory"
+};
+test("tool call keys are stable and policy scoped", () => {
+    const request = {
+        tool_name: "read_file",
+        arguments: { path: "README.md" },
+        side_effects: "read"
+    };
+    assert.equal(toolArgumentsHash(request.arguments).startsWith("sha256:"), true);
+    assert.equal(toolCallKey({ contract, request }), toolCallKey({ contract, request }));
+    assert.notEqual(toolCallKey({ contract, request }), toolCallKey({
+        contract: { ...contract, environment_id: "env_other" },
+        request
+    }));
+    assert.equal(toolCallKey({ contract, request }), toolCallKey({
+        contract,
+        request: {
+            ...request,
+            candidate_id: "candidate_b",
+            plan_id: "tool_plan_other"
+        }
+    }));
+});
+test("tool policy allows read-only configured tools and denies unsafe calls", () => {
+    const allowed = evaluateToolPolicy(contract, {
+        tool_name: "read_file",
+        arguments: { path: "README.md" },
+        side_effects: "read"
+    });
+    assert.equal(allowed.decision, "allow");
+    assert.ok(allowed.decision === "allow" && allowed.dedupeKey);
+    const unknown = evaluateToolPolicy(contract, {
+        tool_name: "write_file",
+        arguments: { path: "README.md" },
+        side_effects: "write"
+    });
+    assert.equal(unknown.decision, "deny");
+    const external = evaluateToolPolicy({ ...contract, allowed_tools: ["fetch"], side_effects: ["external"] }, { tool_name: "fetch", arguments: { url: "https://example.com" }, side_effects: "external" });
+    assert.equal(external.decision, "deny");
+});
+test("tool side effects map to model-fusion side effects", () => {
+    assert.equal(modelFusionSideEffects("none"), "none");
+    assert.equal(modelFusionSideEffects("read"), "read_only");
+    assert.equal(modelFusionSideEffects("write"), "writes_workspace");
+    assert.equal(modelFusionSideEffects("external"), "network");
+    assert.equal(toolSideEffectClassFromModelFusion("none"), "none");
+    assert.equal(toolSideEffectClassFromModelFusion("read_only"), "read");
+    assert.equal(toolSideEffectClassFromModelFusion("writes_workspace"), "write");
+    assert.equal(toolSideEffectClassFromModelFusion("network"), "external");
+    assert.throws(() => toolSideEffectClassFromModelFusion("unknown"));
+});
+test("tool execution result shape remains JSON-safe", () => {
+    const result = {
+        record: {
+            schema: "tool-execution-record.v1",
+            schema_version: "v1",
+            schema_bundle_hash: MODEL_FUSION_SCHEMA_BUNDLE_HASH,
+            producer: "test",
+            producer_version: "0.1.0",
+            producer_git_sha: "0".repeat(40),
+            created_at: "2026-06-16T00:00:00.000Z",
+            execution_id: "exec_1",
+            plan_id: "plan_1",
+            status: "succeeded",
+            output_hash: toolArgumentsHash({ ok: true })
+        },
+        output: { ok: true },
+        deduped: false,
+        decision: { decision: "allow", reason: "test" }
+    };
+    assert.doesNotThrow(() => JSON.stringify(result));
+});

package/dist/test/trace.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/trace.test.js

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { assertFusionTraceEvent, FUSION_TRACE_EVENT_SCHEMA, isFusionTraceEvent, judgeFinalPayload, judgeRequestPayload, judgeThinkingPayload, modelCallFinishedPayload, modelCallStartedPayload } from "../trace.js";
+function validEvent(overrides = {}) {
+    return {
+        schema: FUSION_TRACE_EVENT_SCHEMA,
+        trace_id: "trace_x",
+        span_id: "span_x",
+        seq: 0,
+        ts: Date.now(),
+        component: "judge",
+        event_type: "judge.request",
+        ...overrides
+    };
+}
+test("assertFusionTraceEvent accepts a well-formed event", () => {
+    assert.doesNotThrow(() => assertFusionTraceEvent(validEvent()));
+    assert.equal(isFusionTraceEvent(validEvent()), true);
+});
+test("assertFusionTraceEvent rejects malformed events", () => {
+    assert.throws(() => assertFusionTraceEvent(null));
+    assert.throws(() => assertFusionTraceEvent(validEvent({ schema: "nope" })));
+    assert.throws(() => assertFusionTraceEvent(validEvent({ component: "martian" })));
+    assert.throws(() => assertFusionTraceEvent(validEvent({ event_type: "nope" })));
+    assert.throws(() => assertFusionTraceEvent(validEvent({ trace_id: "" })));
+    assert.throws(() => assertFusionTraceEvent(validEvent({ seq: "x" })));
+    assert.throws(() => assertFusionTraceEvent(validEvent({ payload: [] })));
+    assert.equal(isFusionTraceEvent(validEvent({ component: "x" })), false);
+});
+test("judgeRequestPayload carries the full prompt fields and the turn", () => {
+    const payload = judgeRequestPayload({
+        judgeModel: "j",
+        messages: [{ role: "user" }],
+        trajectories: [{ trajectory_id: "t" }],
+        tools: [],
+        trajectoryIds: ["t"],
+        turn: 2
+    });
+    assert.equal(payload.judge_model, "j");
+    assert.deepEqual(payload.trajectory_ids, ["t"]);
+    assert.equal(payload.turn, 2);
+    assert.ok(Array.isArray(payload.messages));
+    assert.ok(Array.isArray(payload.trajectories));
+});
+test("judgeThinkingPayload carries interim analysis, tool calls, and turn", () => {
+    const payload = judgeThinkingPayload({
+        rawAnalysis: "requested a tool",
+        toolCalls: [{ id: "t1" }],
+        turn: 3
+    });
+    assert.equal(payload.raw_analysis, "requested a tool");
+    assert.deepEqual(payload.tool_calls, [{ id: "t1" }]);
+    assert.equal(payload.turn, 3);
+});
+test("judgeFinalPayload mirrors the final output into the record", () => {
+    const payload = judgeFinalPayload({ content: "answer", usage: { total_tokens: 5 } });
+    assert.equal(payload.final_output, "answer");
+    assert.deepEqual(payload.record, { final_output: "answer" });
+    assert.deepEqual(payload.usage, { total_tokens: 5 });
+});
+test("model-call payloads use snake_case prompt + token fields", () => {
+    const started = modelCallStartedPayload({ model: "m", systemPrompt: "sys", prompt: "task", tools: ["run"] });
+    assert.equal(started.system_prompt, "sys");
+    assert.equal(started.prompt, "task");
+    assert.deepEqual(started.tools, ["run"]);
+    const finished = modelCallFinishedPayload({
+        model: "m",
+        finalOutput: "done",
+        finishReason: "stop",
+        usage: { total_tokens: 9 }
+    });
+    assert.equal(finished.final_output, "done");
+    assert.equal(finished.finish_reason, "stop");
+    assert.equal(finished.content_preview, "done");
+});

package/dist/tool-executor.d.ts

@@ -0,0 +1,58 @@
+import type { JsonValue } from "./jcs.js";
+import type { ModelFusionSideEffects, ToolExecutionRecordV1 } from "./model-fusion.js";
+export type ToolSideEffectClass = "none" | "read" | "write" | "external";
+export type ToolExecutorMode = "demo_safe" | "policy_bound";
+export type ToolPolicyDecision = {
+    decision: "allow";
+    reason: string;
+    dedupeKey?: string;
+} | {
+    decision: "deny";
+    reason: string;
+    errorKind: "tool_denied" | "capability_missing";
+};
+export type ToolDefinition = {
+    tool_name: string;
+    side_effects: ToolSideEffectClass;
+    description?: string;
+};
+export type ToolExecutorLimits = {
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+};
+export type ToolExecutorBudget = {
+    maxSpendUsd?: number;
+};
+export type ToolExecutorContract = {
+    executor_id: string;
+    mode: ToolExecutorMode;
+    environment_id: string;
+    tool_policy_id: string;
+    allowed_tools: string[];
+    side_effects: ToolSideEffectClass[];
+    limits?: ToolExecutorLimits;
+    timeoutMs?: number;
+    budget?: ToolExecutorBudget;
+    audit_sink?: string;
+};
+export type ToolExecutionRequest = {
+    candidate_id?: string;
+    plan_id?: string;
+    tool_name: string;
+    arguments: JsonValue;
+    side_effects: ToolSideEffectClass;
+};
+export type ToolExecutionResult = {
+    record: ToolExecutionRecordV1;
+    output?: JsonValue;
+    deduped: boolean;
+    decision: ToolPolicyDecision;
+};
+export declare function toolArgumentsHash(args: JsonValue): string;
+export declare function toolCallKey(input: {
+    contract: ToolExecutorContract;
+    request: ToolExecutionRequest;
+}): string;
+export declare function modelFusionSideEffects(sideEffects: ToolSideEffectClass): ModelFusionSideEffects;
+export declare function toolSideEffectClassFromModelFusion(sideEffects: ModelFusionSideEffects): ToolSideEffectClass;
+export declare function evaluateToolPolicy(contract: ToolExecutorContract, request: ToolExecutionRequest): ToolPolicyDecision;

package/dist/tool-executor.js

@@ -0,0 +1,80 @@
+import { hashCanonical, hashCanonicalSha256 } from "./hash.js";
+export function toolArgumentsHash(args) {
+    return hashCanonicalSha256(args);
+}
+export function toolCallKey(input) {
+    return hashCanonical({
+        executor_id: input.contract.executor_id,
+        environment_id: input.contract.environment_id,
+        tool_policy_id: input.contract.tool_policy_id,
+        tool_name: input.request.tool_name,
+        side_effects: input.request.side_effects,
+        arguments_hash: toolArgumentsHash(input.request.arguments)
+    });
+}
+export function modelFusionSideEffects(sideEffects) {
+    switch (sideEffects) {
+        case "none":
+            return "none";
+        case "read":
+            return "read_only";
+        case "write":
+            return "writes_workspace";
+        case "external":
+            return "network";
+        default: {
+            const exhausted = sideEffects;
+            throw new Error(`unknown side effect class: ${String(exhausted)}`);
+        }
+    }
+}
+export function toolSideEffectClassFromModelFusion(sideEffects) {
+    switch (sideEffects) {
+        case "none":
+            return "none";
+        case "read_only":
+            return "read";
+        case "writes_workspace":
+            return "write";
+        case "network":
+            return "external";
+        case "tool_execution":
+        case "unknown":
+            throw new Error(`unsupported tool side effect: ${sideEffects}`);
+        default: {
+            const exhausted = sideEffects;
+            throw new Error(`unknown model-fusion side effect: ${String(exhausted)}`);
+        }
+    }
+}
+export function evaluateToolPolicy(contract, request) {
+    if (!contract.allowed_tools.includes(request.tool_name)) {
+        return {
+            decision: "deny",
+            reason: `tool ${request.tool_name} is not allowed by ${contract.tool_policy_id}`,
+            errorKind: "tool_denied"
+        };
+    }
+    if (!contract.side_effects.includes(request.side_effects)) {
+        return {
+            decision: "deny",
+            reason: `side effect ${request.side_effects} is not allowed by ${contract.tool_policy_id}`,
+            errorKind: "tool_denied"
+        };
+    }
+    if (contract.mode === "demo_safe" &&
+        (request.side_effects === "write" || request.side_effects === "external")) {
+        return {
+            decision: "deny",
+            reason: `demo_safe executor denies ${request.side_effects} tool calls by default`,
+            errorKind: "tool_denied"
+        };
+    }
+    return {
+        decision: "allow",
+        reason: "allowed by tool executor policy",
+        dedupeKey: request.side_effects === "none" || request.side_effects === "read"
+            ? toolCallKey({ contract, request })
+            : undefined
+    };
+}

package/dist/trace.d.ts

@@ -0,0 +1,119 @@
+/**
+ * fusion-trace-event.v1 — fire-and-forget observability emitter.
+ *
+ * This is the canonical TypeScript implementation of the standalone fusion-trace
+ * contract (see fusionkit `spec/fusion-trace`). It lives in `@fusionkit/protocol`
+ * (a dependency-free leaf) so the gateway, ensemble harness, the AI SDK worktree
+ * agent, and the CLI can all emit against the same shape without import cycles.
+ *
+ * Emission is a no-op unless `FUSION_TRACE_URL` or `FUSION_TRACE_DIR` is set, so
+ * normal runs are never blocked by, or coupled to, the collector.
+ */
+export declare const FUSION_TRACE_EVENT_SCHEMA: "fusion-trace-event.v1";
+export declare const FUSION_TRACE_EVENT_VERSION: "1.0.0";
+export declare const TRACE_ID_HEADER = "x-fusion-trace-id";
+export declare const TRACE_SPAN_HEADER = "x-fusion-span-id";
+export declare const TRACE_PARENT_SPAN_HEADER = "x-fusion-parent-span-id";
+export declare const TRACE_CANDIDATE_HEADER = "x-fusion-candidate-id";
+export type FusionTraceComponent = "gateway" | "ensemble" | "agent" | "panel-model" | "judge" | "synthesis" | "cursor-bridge";
+export type FusionTraceEventType = "session.started" | "session.finished" | "harness.candidate.started" | "harness.candidate.finished" | "trajectory.step" | "model.call.started" | "model.call.finished" | "judge.request" | "judge.thinking" | "judge.scored" | "judge.synthesis" | "judge.final" | "tool.execution" | "cursor.route" | "log";
+/** Runtime-iterable mirrors of the closed unions (used by the validator). */
+export declare const FUSION_TRACE_COMPONENTS: readonly FusionTraceComponent[];
+export declare const FUSION_TRACE_EVENT_TYPES: readonly FusionTraceEventType[];
+export type FusionTraceEvent = {
+    schema: typeof FUSION_TRACE_EVENT_SCHEMA;
+    schema_version?: string;
+    trace_id: string;
+    span_id: string;
+    parent_span_id?: string;
+    seq: number;
+    ts: number;
+    component: FusionTraceComponent;
+    event_type: FusionTraceEventType;
+    session_id?: string;
+    candidate_id?: string;
+    model_id?: string;
+    payload?: Record<string, unknown>;
+};
+export type EmitInput = {
+    component: FusionTraceComponent;
+    event_type: FusionTraceEventType;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    candidateId?: string;
+    modelId?: string;
+    sessionId?: string;
+    payload?: Record<string, unknown>;
+};
+export declare function newTraceId(): string;
+export declare function newSpanId(): string;
+export declare function ambientTraceId(): string | undefined;
+export declare class TraceEmitter {
+    private readonly url?;
+    private readonly dir?;
+    private readonly enabled;
+    private seq;
+    private dirReady;
+    constructor(config?: {
+        url?: string;
+        dir?: string;
+    });
+    isEnabled(): boolean;
+    emit(input: EmitInput): void;
+    private writeJsonl;
+    private post;
+}
+export declare function getTraceEmitter(): TraceEmitter;
+export declare function emitTrace(input: EmitInput): void;
+/**
+ * Assert that `value` is a well-formed wire `FusionTraceEvent`. Hand-written
+ * (Node-only, no deps) to match the `assertModelFusionRecord` style, so both the
+ * emitter side and the scope ingest boundary validate against one contract.
+ */
+export declare function assertFusionTraceEvent(value: unknown): asserts value is FusionTraceEvent;
+export declare function isFusionTraceEvent(value: unknown): value is FusionTraceEvent;
+export declare function judgeRequestPayload(input: {
+    judgeModel?: string;
+    messages: unknown;
+    trajectories: unknown;
+    tools?: unknown;
+    toolChoice?: unknown;
+    trajectoryIds?: string[];
+    /** 1-based user-turn index (a follow-up message is a new turn). */
+    turn?: number;
+}): Record<string, unknown>;
+/** An intermediate (tool-calling) judge step within a turn. */
+export declare function judgeThinkingPayload(input: {
+    rawAnalysis?: string;
+    toolCalls?: unknown;
+    usage?: unknown;
+    turn?: number;
+}): Record<string, unknown>;
+export declare function judgeFinalPayload(input: {
+    finalOutput?: string;
+    content?: string;
+    toolCalls?: unknown;
+    usage?: unknown;
+    httpStatus?: number;
+    error?: string;
+    turn?: number;
+}): Record<string, unknown>;
+export declare function modelCallStartedPayload(input: {
+    model: string;
+    systemPrompt?: string;
+    prompt?: string;
+    tools?: string[];
+    turn?: number;
+}): Record<string, unknown>;
+export declare function modelCallFinishedPayload(input: {
+    model: string;
+    finalOutput?: string;
+    usage?: unknown;
+    finishReason?: string;
+    stepCount?: number;
+    toolCallCount?: number;
+    latencyS?: number;
+    error?: string;
+    turn?: number;
+}): Record<string, unknown>;