@fusionkit/protocol 0.1.0

package/dist/receipt-story.js

@@ -0,0 +1,127 @@
+function short(hash, length = 12) {
+    return hash.slice(0, length);
+}
+export function summarizeRunEvent(event) {
+    switch (event.type) {
+        case "run.created":
+            return { tone: "info", label: "run.created", detail: "contract issued" };
+        case "run.claimed":
+            return {
+                tone: "info",
+                label: "run.claimed",
+                detail: `${event.runnerId} ${event.runnerKeyId}`
+            };
+        case "workspace.materialized":
+            return {
+                tone: "info",
+                label: "workspace.materialized",
+                detail: `manifest ${short(event.manifestHash)}`
+            };
+        case "policy.evaluated":
+            return {
+                tone: event.decision === "allow" ? "ok" : "warn",
+                label: "policy.evaluated",
+                detail: event.reason
+            };
+        case "consent.requested":
+            return {
+                tone: "warn",
+                label: "consent.requested",
+                detail: event.requirement
+            };
+        case "consent.granted":
+            return {
+                tone: "ok",
+                label: "consent.granted",
+                detail: `${event.actor.kind}:${event.actor.id}`
+            };
+        case "secret.released":
+            return {
+                tone: "warn",
+                label: "secret.released",
+                detail: `${event.name} (${event.scope})`
+            };
+        case "command.executed":
+            return {
+                tone: event.exitCode === 0 ? "ok" : "err",
+                label: "command.executed",
+                detail: `argv ${short(event.argvHash)} exit ${event.exitCode}`
+            };
+        case "file.changed":
+            return {
+                tone: "plain",
+                label: "file.changed",
+                detail: `${event.path} ${short(event.contentHash)}`
+            };
+        case "network.connected":
+            return {
+                tone: event.decision === "allowed" ? "ok" : "warn",
+                label: "network.connected",
+                detail: `${event.host} ${event.decision}`
+            };
+        case "model.called":
+            return {
+                tone: "info",
+                label: "model.called",
+                detail: `${event.provider}/${event.model}`
+            };
+        case "boundary.crossed":
+            return {
+                tone: "warn",
+                label: "boundary.crossed",
+                detail: `${event.direction}: ${event.dataClass} ${short(event.contentHash)}`
+            };
+        case "artifact.created":
+            return {
+                tone: "info",
+                label: "artifact.created",
+                detail: `${event.kind} ${short(event.hash)}`
+            };
+        case "checkpoint.created":
+            return {
+                tone: "info",
+                label: "checkpoint.created",
+                detail: `${event.checkpointId} (${event.tier})`
+            };
+        case "run.completed":
+            return { tone: "ok", label: "run.completed", detail: "completed" };
+        case "run.failed":
+            return {
+                tone: "err",
+                label: "run.failed",
+                detail: `${event.failure}: ${event.message}`
+            };
+        case "run.cancelled":
+            return {
+                tone: "warn",
+                label: "run.cancelled",
+                detail: `${event.actor.kind}:${event.actor.id}`
+            };
+        default: {
+            const exhausted = event;
+            return { tone: "plain", label: "unknown", detail: String(exhausted) };
+        }
+    }
+}
+export function buildReceiptStory(bundle) {
+    const { contract, receipt } = bundle;
+    return {
+        runId: receipt.runId,
+        status: receipt.status,
+        actor: `${contract.requestedBy.kind}:${contract.requestedBy.id}`,
+        agent: contract.agent.kind,
+        isolation: receipt.runner.isolation ?? "process",
+        workspace: {
+            baseRef: contract.workspace.baseRef,
+            manifestHash: receipt.workspaceIn.manifestHash,
+            diffHash: receipt.workspaceOut.diffHash,
+            artifactCount: receipt.workspaceOut.artifactHashes.length
+        },
+        policyHash: contract.policyHash,
+        secrets: receipt.secretsReleased.map((s) => `${s.name} (${s.scope})`),
+        network: receipt.networkAccessed.map((n) => `${n.host} ${n.decision}`),
+        eventCount: receipt.eventCount,
+        eventsHead: receipt.eventsHead,
+        verificationCommand: "warrant verify <bundle.json>"
+    };
+}

package/dist/receipt.d.ts

@@ -0,0 +1,20 @@
+import type { ChainedEvent, Receipt, ReceiptBundle, Signature } from "./types.js";
+export declare function signReceipt(receipt: Receipt, privateKeyPem: string, publicKeyPem: string, signer: Signature["signer"]): Receipt;
+export declare function verifyReceiptSignature(receipt: Receipt, signer: Signature["signer"], publicKeyPem: string): boolean;
+export type BundleVerification = {
+    ok: boolean;
+    problems: string[];
+};
+export type RunnerReceiptVerificationInput = {
+    contract: ReceiptBundle["contract"];
+    receipt: Receipt;
+    events: ChainedEvent[];
+    runnerPublicKeyPem: string;
+};
+/**
+ * Verify the runner-produced receipt against the signed contract and stored
+ * event chain before any plane countersignature exists. This is the plane's
+ * completion-time check and the core of offline bundle verification.
+ */
+export declare function verifyRunnerReceipt(input: RunnerReceiptVerificationInput): BundleVerification;
+export declare function verifyReceiptBundle(bundle: ReceiptBundle): BundleVerification;

package/dist/receipt.js

@@ -0,0 +1,162 @@
+import { contractHash, verifyContractSignature } from "./contract.js";
+import { hashCanonical } from "./hash.js";
+import { keyIdFromPublicPem, signData, verifyData } from "./keys.js";
+import { verifyChain } from "./chain.js";
+function signablePayload(receipt) {
+    const { signatures: _signatures, ...unsigned } = receipt;
+    return hashCanonical(unsigned);
+}
+export function signReceipt(receipt, privateKeyPem, publicKeyPem, signer) {
+    const payload = signablePayload(receipt);
+    const signature = {
+        keyId: keyIdFromPublicPem(publicKeyPem),
+        alg: "ed25519",
+        signer,
+        sig: signData(privateKeyPem, payload)
+    };
+    return { ...receipt, signatures: [...receipt.signatures, signature] };
+}
+export function verifyReceiptSignature(receipt, signer, publicKeyPem) {
+    const payload = signablePayload(receipt);
+    const signature = receipt.signatures.find((s) => s.signer === signer);
+    if (!signature)
+        return false;
+    if (keyIdFromPublicPem(publicKeyPem) !== signature.keyId)
+        return false;
+    return verifyData(publicKeyPem, payload, signature.sig);
+}
+/** Element-wise equality for two already-sorted arrays. */
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+function secretReleaseKey(record) {
+    return `${record.name}\u0000${record.scope}\u0000${record.ts}`;
+}
+function terminalEventMatches(event, status) {
+    switch (status) {
+        case "completed":
+            return event.type === "run.completed";
+        case "failed":
+            return event.type === "run.failed";
+        case "cancelled":
+            return event.type === "run.cancelled";
+        default: {
+            const exhausted = status;
+            throw new Error(`unreachable status: ${String(exhausted)}`);
+        }
+    }
+}
+/**
+ * Verify the runner-produced receipt against the signed contract and stored
+ * event chain before any plane countersignature exists. This is the plane's
+ * completion-time check and the core of offline bundle verification.
+ */
+export function verifyRunnerReceipt(input) {
+    const problems = [];
+    const { contract, receipt, events, runnerPublicKeyPem } = input;
+    const expectedContractHash = contractHash(contract);
+    if (receipt.runId !== contract.runId) {
+        problems.push("receipt.runId does not match the contract");
+    }
+    if (receipt.contractHash !== expectedContractHash) {
+        problems.push("receipt.contractHash does not match the contract");
+    }
+    if (receipt.runner.keyId !== keyIdFromPublicPem(runnerPublicKeyPem)) {
+        problems.push("receipt runner key id does not match the enrolled runner key");
+    }
+    if (receipt.runner.pool !== contract.runner.pool) {
+        problems.push("receipt runner pool does not match the contract");
+    }
+    if (!verifyReceiptSignature(receipt, "runner", runnerPublicKeyPem)) {
+        problems.push("receipt runner signature invalid");
+    }
+    const chain = verifyChain(events, expectedContractHash);
+    if (!chain.ok) {
+        problems.push(`event chain broken at seq ${chain.brokenAtSeq}: ${chain.reason}`);
+    }
+    const last = events[events.length - 1];
+    if (!last) {
+        problems.push("event chain is empty");
+    }
+    else {
+        if (receipt.eventsHead !== last.hash) {
+            problems.push("receipt.eventsHead does not match the last event hash");
+        }
+        if (receipt.eventCount !== events.length) {
+            problems.push("receipt.eventCount does not match the event chain");
+        }
+        if (!terminalEventMatches(last.event, receipt.status)) {
+            problems.push("terminal event does not match receipt status");
+        }
+    }
+    if (receipt.workspaceIn.baseRef !== contract.workspace.baseRef) {
+        problems.push("receipt.workspaceIn.baseRef does not match the contract");
+    }
+    const manifestHash = hashCanonical(contract.workspace);
+    if (receipt.workspaceIn.manifestHash !== manifestHash) {
+        problems.push("receipt.workspaceIn.manifestHash does not match the contract");
+    }
+    const releasedInEvents = events
+        .filter((e) => e.event.type === "secret.released")
+        .map((e) => e.event.type === "secret.released"
+        ? { name: e.event.name, scope: e.event.scope, ts: e.ts }
+        : { name: "", scope: "", ts: "" })
+        .map(secretReleaseKey)
+        .sort();
+    const releasedInReceipt = receipt.secretsReleased.map(secretReleaseKey).sort();
+    if (!arraysEqual(releasedInEvents, releasedInReceipt)) {
+        problems.push("secretsReleased does not match secret.released events");
+    }
+    if (receipt.workspaceOut.diffHash !== "") {
+        const artifactHashes = new Set(events
+            .filter((e) => e.event.type === "artifact.created")
+            .map((e) => (e.event.type === "artifact.created" ? e.event.hash : "")));
+        if (!artifactHashes.has(receipt.workspaceOut.diffHash)) {
+            problems.push("workspaceOut.diffHash has no matching artifact.created event");
+        }
+    }
+    return { ok: problems.length === 0, problems };
+}
+/**
+ * Fully offline verification of a receipt bundle. Trusts nothing but the
+ * keys embedded in the bundle, which callers should pin or resolve from
+ * the org's published key manifest.
+ */
+function verifyReceiptBundleUnchecked(bundle) {
+    const problems = [];
+    const { contract, receipt, events, keys } = bundle;
+    if (!verifyContractSignature(contract, "plane", (keyId) => keyId === keyIdFromPublicPem(keys.planePublicKeyPem)
+        ? keys.planePublicKeyPem
+        : undefined)) {
+        problems.push("contract plane signature invalid");
+    }
+    problems.push(...verifyRunnerReceipt({
+        contract,
+        receipt,
+        events,
+        runnerPublicKeyPem: keys.runnerPublicKeyPem
+    }).problems);
+    if (!verifyReceiptSignature(receipt, "plane", keys.planePublicKeyPem)) {
+        problems.push("receipt plane countersignature invalid");
+    }
+    return { ok: problems.length === 0, problems };
+}
+export function verifyReceiptBundle(bundle) {
+    try {
+        return verifyReceiptBundleUnchecked(bundle);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            problems: [
+                `bundle is malformed: ${error instanceof Error ? error.message : String(error)}`
+            ]
+        };
+    }
+}

package/dist/test/model-fusion.test.d.ts

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

package/dist/test/model-fusion.test.js

@@ -0,0 +1,213 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { artifactHash, assertArtifactRefV1, assertBenchmarkTaskRecordV1, assertEnsembleReceiptV1, assertHarnessCandidateRecordV1, assertHarnessRunRequestV1, assertHarnessRunResultV1, assertJudgeSynthesisRecordV1, assertModelCallRecordV1, assertModelFusionRecord, assertToolCallPlanV1, assertToolExecutionRecordV1, hashCanonicalSha256, executeHarnessTask, MODEL_FUSION_SCHEMA_BUNDLE_HASH, MODEL_FUSION_OPENAPI_SOURCE_HASH, MODEL_FUSION_SCHEMA_NAMES, requestHash, responseHash, schemaBundleHash, sha256PrefixedHex } from "../index.js";
+const FIXTURE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "src", "fixtures", "model-fusion-contract");
+const SCHEMAS = [
+    "model-call-record.v1",
+    "harness-run-request.v1",
+    "harness-run-result.v1",
+    "harness-candidate-record.v1",
+    "judge-synthesis-record.v1",
+    "benchmark-task-record.v1",
+    "artifact-ref.v1",
+    "tool-call-plan.v1",
+    "tool-execution-record.v1",
+    "ensemble-receipt.v1"
+];
+const VALIDATORS = {
+    "model-call-record.v1": assertModelCallRecordV1,
+    "harness-run-request.v1": assertHarnessRunRequestV1,
+    "harness-run-result.v1": assertHarnessRunResultV1,
+    "harness-candidate-record.v1": assertHarnessCandidateRecordV1,
+    "judge-synthesis-record.v1": assertJudgeSynthesisRecordV1,
+    "benchmark-task-record.v1": assertBenchmarkTaskRecordV1,
+    "artifact-ref.v1": assertArtifactRefV1,
+    "tool-call-plan.v1": assertToolCallPlanV1,
+    "tool-execution-record.v1": assertToolExecutionRecordV1,
+    "ensemble-receipt.v1": assertEnsembleReceiptV1
+};
+function readFixture(schema, variant) {
+    return JSON.parse(readFileSync(join(FIXTURE_ROOT, schema, `${variant}.json`), "utf8"));
+}
+test("model-fusion schema constants include the MF-02 record set", () => {
+    assert.deepEqual([...MODEL_FUSION_SCHEMA_NAMES], [...SCHEMAS]);
+});
+test("model-fusion fixtures carry the exported schema bundle hash", () => {
+    assert.match(MODEL_FUSION_SCHEMA_BUNDLE_HASH, /^sha256:[0-9a-f]{64}$/);
+    for (const schema of SCHEMAS) {
+        for (const variant of ["minimal", "realistic"]) {
+            const fixture = readFixture(schema, variant);
+            assert.equal(fixture.schema_bundle_hash, MODEL_FUSION_SCHEMA_BUNDLE_HASH);
+        }
+    }
+});
+test("specific validators accept copied MF-00 minimal and realistic fixtures", () => {
+    for (const schema of SCHEMAS) {
+        const validate = VALIDATORS[schema];
+        validate(readFixture(schema, "minimal"));
+        validate(readFixture(schema, "realistic"));
+    }
+});
+test("union validator accepts every copied model-fusion fixture", () => {
+    for (const schema of SCHEMAS) {
+        assertModelFusionRecord(readFixture(schema, "minimal"));
+        assertModelFusionRecord(readFixture(schema, "realistic"));
+    }
+});
+test("model-fusion validators reject wrong schema and missing required fields", () => {
+    const call = readFixture("model-call-record.v1", "minimal");
+    assertModelCallRecordV1(call);
+    assert.throws(() => assertModelCallRecordV1({ ...call, schema: "artifact-ref.v1" }), /schema must be model-call-record.v1/);
+    const { call_id: _callId, ...missingCallId } = call;
+    assert.throws(() => assertModelCallRecordV1(missingCallId), /call_id/);
+    assert.throws(() => assertModelFusionRecord({ schema: "unknown.v1" }), /unsupported/);
+});
+test("model-fusion validators reject bad enum and hash values", () => {
+    const plan = readFixture("tool-call-plan.v1", "minimal");
+    assert.throws(() => assertToolCallPlanV1({ ...plan, status: "done" }), /status/);
+    assert.throws(() => assertToolCallPlanV1({ ...plan, arguments_hash: "not-a-hash" }), /arguments_hash/);
+});
+test("model-fusion validators reject unsupported fields", () => {
+    const call = readFixture("model-call-record.v1", "minimal");
+    assert.throws(() => assertModelCallRecordV1({ ...call, extra_field: true }), /unsupported field/);
+    const messages = call.messages;
+    assert.throws(() => assertModelCallRecordV1({
+        ...call,
+        messages: [{ ...messages[0], hidden: true }]
+    }), /unsupported field/);
+    const result = readFixture("harness-run-result.v1", "realistic");
+    const artifacts = result.artifacts;
+    assert.throws(() => assertHarnessRunResultV1({
+        ...result,
+        artifacts: [{ ...artifacts[0], schema: "artifact-ref.v1" }]
+    }), /unsupported field/);
+});
+test("harness candidate metadata accepts nested microVM hardening evidence", () => {
+    const candidate = readFixture("harness-candidate-record.v1", "minimal");
+    const withHardeningMetadata = {
+        ...candidate,
+        metadata: {
+            hardening: {
+                requested_isolation: "microvm",
+                actual_isolation: "vercel-sandbox",
+                provider: "vercel-sandbox",
+                runtime: {
+                    engine: "firecracker",
+                    node_version: "22.x"
+                },
+                sandbox: {
+                    sandbox_id: "sbx_microvm_fixture",
+                    snapshot_id: "snap_microvm_fixture",
+                    persistent: false
+                },
+                network: {
+                    default_deny: true,
+                    allowed_hosts: []
+                },
+                cleanup: {
+                    status: "succeeded",
+                    duration_ms: 17
+                },
+                secrets: {
+                    mounted: false
+                }
+            }
+        }
+    };
+    assertHarnessCandidateRecordV1(withHardeningMetadata);
+    assertModelFusionRecord(withHardeningMetadata);
+    assert.throws(() => assertHarnessCandidateRecordV1({
+        ...candidate,
+        microvm: withHardeningMetadata.metadata
+    }), /unsupported field/);
+});
+test("harness candidate metadata accepts disclosure joins without top-level schema changes", () => {
+    const candidate = readFixture("harness-candidate-record.v1", "minimal");
+    const withDisclosureMetadata = {
+        ...candidate,
+        metadata: {
+            disclosures: [
+                {
+                    candidate_id: "candidate_a",
+                    tool_call_id: "tool_call_readme",
+                    plan_id: "tool_plan_readme",
+                    execution_id: "tool_exec_readme",
+                    run_id: "run_secret_disclosure",
+                    content_hash: "sha256:" + "a".repeat(64),
+                    data_class: "session-log",
+                    direction: "out",
+                    policy_id: "policy_readonly",
+                    environment_id: "env_local",
+                    secret_names: ["API_TOKEN"],
+                    injected_env_names: ["API_TOKEN"],
+                    redaction_status: "redacted"
+                }
+            ]
+        }
+    };
+    assertHarnessCandidateRecordV1(withDisclosureMetadata);
+    assertModelFusionRecord(withDisclosureMetadata);
+    assert.throws(() => assertHarnessCandidateRecordV1({
+        ...candidate,
+        disclosures: withDisclosureMetadata.metadata
+    }), /unsupported field/);
+});
+test("model-fusion hash helpers return sha256-prefixed hashes", () => {
+    assert.match(sha256PrefixedHex("hello"), /^sha256:[0-9a-f]{64}$/);
+    assert.match(artifactHash(Buffer.from("artifact")), /^sha256:[0-9a-f]{64}$/);
+    assert.match(requestHash({ b: 2, a: 1 }), /^sha256:[0-9a-f]{64}$/);
+    assert.equal(requestHash({ b: 2, a: 1 }), responseHash({ a: 1, b: 2 }));
+    assert.equal(hashCanonicalSha256({ z: true }), requestHash({ z: true }));
+    assert.match(schemaBundleHash({
+        "b.schema.json": { b: true },
+        "a.schema.json": { a: true }
+    }), /^sha256:[0-9a-f]{64}$/);
+});
+test("model-fusion exports are available from the protocol package entrypoint", () => {
+    assert.equal(typeof assertModelFusionRecord, "function");
+    assert.equal(typeof assertHarnessRunRequestV1, "function");
+    assert.equal(typeof requestHash, "function");
+});
+test("generated OpenAPI client and service models are exported", async () => {
+    assert.match(MODEL_FUSION_OPENAPI_SOURCE_HASH, /^sha256:[0-9a-f]{64}$/);
+    const request = {
+        request_id: "req_generated",
+        task_id: "task_generated",
+        source_repo: "handoffkit",
+        base_git_sha: "0".repeat(40),
+        harness_kind: "generic",
+        prompt_hash: requestHash("generated"),
+        allowed_tools: ["read_file"],
+        side_effects: "read_only",
+        harness_run_request: {
+            schema: "harness-run-request.v1",
+            schema_version: "v1",
+            schema_bundle_hash: MODEL_FUSION_SCHEMA_BUNDLE_HASH,
+            persisted_json: {}
+        }
+    };
+    const result = await executeHarnessTask({
+        baseUrl: "https://executor.example",
+        fetch: async (url, init) => {
+            assert.equal(String(url), "https://executor.example/v1/harness-executions");
+            assert.equal(init?.method, "POST");
+            assert.match(String(init?.body), /req_generated/);
+            return new Response(JSON.stringify({
+                request_id: request.request_id,
+                result_id: "result_generated",
+                status: "succeeded",
+                candidate_ids: [],
+                harness_run_result: {
+                    schema: "harness-run-result.v1",
+                    schema_version: "v1",
+                    schema_bundle_hash: MODEL_FUSION_SCHEMA_BUNDLE_HASH,
+                    persisted_json: {}
+                }
+            }), { status: 200, headers: { "content-type": "application/json" } });
+        }
+    }, request);
+    assert.equal(result.result_id, "result_generated");
+});

package/dist/test/protocol.test.d.ts

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