@fusionkit/protocol 0.1.0

package/dist/model-fusion.js

@@ -0,0 +1,596 @@
+export const MODEL_FUSION_SCHEMA_NAMES = [
+    "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"
+];
+export const MODEL_FUSION_SCHEMA_BUNDLE_HASH = "sha256:75792f89c091b6ab4fd317a15fb03fd73438563dceff5ccf9f5d7c752dbf35f3";
+const HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const GIT_SHA_PATTERN = /^[a-f0-9]{40}$/;
+const STATUSES = [
+    "pending",
+    "running",
+    "succeeded",
+    "failed",
+    "canceled",
+    "requires_action",
+    "skipped",
+    "unsupported"
+];
+const SIDE_EFFECTS = [
+    "none",
+    "read_only",
+    "writes_workspace",
+    "network",
+    "tool_execution",
+    "unknown"
+];
+const HARNESS_KINDS = [
+    "generic",
+    "cursor",
+    "claude_code",
+    "codex",
+    "openai_responses"
+];
+const CAPABILITY_STATUSES = [
+    "supported",
+    "unsupported",
+    "degraded",
+    "unknown"
+];
+const ARTIFACT_KINDS = [
+    "patch",
+    "log",
+    "transcript",
+    "metrics",
+    "benchmark_task",
+    "worktree",
+    "receipt",
+    "other"
+];
+const REDACTION_STATUSES = [
+    "synthetic",
+    "redacted",
+    "raw"
+];
+const ERROR_KINDS = [
+    "none",
+    "provider_error",
+    "validation_error",
+    "timeout",
+    "rate_limited",
+    "tool_denied",
+    "secret_denied",
+    "capability_missing",
+    "internal_error"
+];
+const CHAT_ROLES = ["system", "user", "assistant", "tool"];
+const BENCHMARK_TASK_KINDS = ["model_fusion", "harness_coding"];
+const BENCHMARK_SOURCE_REPOS = ["fusionkit", "handoffkit", "cursorkit", "mlx-lm"];
+const BENCHMARK_SCORER_KINDS = ["exact", "contains", "record_join", "custom"];
+const JUDGE_DECISIONS = [
+    "synthesize",
+    "select_candidate",
+    "repair_required",
+    "failed"
+];
+function hasString(values, value) {
+    return typeof value === "string" && values.includes(value);
+}
+function assertObject(value, context) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${context} must be an object`);
+    }
+}
+function assertAllowedKeys(value, allowedKeys, context) {
+    const allowed = new Set(allowedKeys);
+    const unexpected = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unexpected.length > 0) {
+        throw new Error(`${context} contains unsupported field(s): ${unexpected.join(", ")}`);
+    }
+}
+function assertString(value, context) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`${context} must be a non-empty string`);
+    }
+}
+function assertOptionalString(value, context) {
+    if (value !== undefined)
+        assertString(value, context);
+}
+function assertNumber(value, context) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${context} must be a finite number`);
+    }
+}
+function assertOptionalNumber(value, context) {
+    if (value !== undefined)
+        assertNumber(value, context);
+}
+function assertBoolean(value, context) {
+    if (typeof value !== "boolean")
+        throw new Error(`${context} must be a boolean`);
+}
+function assertHash(value, context) {
+    if (typeof value !== "string" || !HASH_PATTERN.test(value)) {
+        throw new Error(`${context} must be a sha256:<64 hex> hash`);
+    }
+}
+function assertGitSha(value, context) {
+    if (typeof value !== "string" || !GIT_SHA_PATTERN.test(value)) {
+        throw new Error(`${context} must be a 40-character git SHA`);
+    }
+}
+function assertDateTime(value, context) {
+    assertString(value, context);
+    if (Number.isNaN(Date.parse(value))) {
+        throw new Error(`${context} must be an RFC 3339 date-time string`);
+    }
+}
+function assertStringArray(value, context, minItems = 0) {
+    if (!Array.isArray(value) || value.length < minItems) {
+        throw new Error(`${context} must be an array with at least ${minItems} item(s)`);
+    }
+    value.forEach((item, index) => assertString(item, `${context}[${index}]`));
+}
+function assertEnum(value, values, context) {
+    if (!hasString(values, value)) {
+        throw new Error(`${context} is not a supported value`);
+    }
+}
+function assertStatus(value, context) {
+    assertEnum(value, STATUSES, context);
+}
+function assertSideEffects(value, context) {
+    assertEnum(value, SIDE_EFFECTS, context);
+}
+function assertHarnessKind(value, context) {
+    assertEnum(value, HARNESS_KINDS, context);
+}
+function assertCapabilityMap(value, context) {
+    assertObject(value, context);
+    for (const [key, status] of Object.entries(value)) {
+        assertEnum(status, CAPABILITY_STATUSES, `${context}.${key}`);
+    }
+}
+function assertError(value, context) {
+    assertObject(value, context);
+    assertAllowedKeys(value, ["kind", "message", "retryable"], context);
+    assertEnum(value.kind, ERROR_KINDS, `${context}.kind`);
+    assertOptionalString(value.message, `${context}.message`);
+    if (value.retryable !== undefined && typeof value.retryable !== "boolean") {
+        throw new Error(`${context}.retryable must be a boolean`);
+    }
+}
+function assertArtifact(value, context, includeMetadata = false) {
+    assertObject(value, context);
+    assertAllowedKeys(value, [
+        ...(includeMetadata
+            ? [
+                "schema",
+                "schema_version",
+                "schema_bundle_hash",
+                "producer",
+                "producer_version",
+                "producer_git_sha",
+                "created_at"
+            ]
+            : []),
+        "artifact_id",
+        "kind",
+        "uri",
+        "hash",
+        "redaction_status"
+    ], context);
+    assertString(value.artifact_id, `${context}.artifact_id`);
+    assertEnum(value.kind, ARTIFACT_KINDS, `${context}.kind`);
+    assertOptionalString(value.uri, `${context}.uri`);
+    assertHash(value.hash, `${context}.hash`);
+    if (value.redaction_status !== undefined) {
+        assertEnum(value.redaction_status, REDACTION_STATUSES, `${context}.redaction_status`);
+    }
+}
+function assertArtifacts(value, context) {
+    if (!Array.isArray(value))
+        throw new Error(`${context} must be an array`);
+    value.forEach((item, index) => assertArtifact(item, `${context}[${index}]`));
+}
+function assertMetadata(value, schema) {
+    if (value.schema !== schema)
+        throw new Error(`schema must be ${schema}`);
+    if (value.schema_version !== "v1")
+        throw new Error("schema_version must be v1");
+    assertHash(value.schema_bundle_hash, "schema_bundle_hash");
+    assertString(value.producer, "producer");
+    assertString(value.producer_version, "producer_version");
+    assertGitSha(value.producer_git_sha, "producer_git_sha");
+    assertDateTime(value.created_at, "created_at");
+}
+function assertChatMessages(value, context) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`${context} must include at least one chat message`);
+    }
+    value.forEach((item, index) => {
+        assertObject(item, `${context}[${index}]`);
+        assertAllowedKeys(item, ["role", "content"], `${context}[${index}]`);
+        assertEnum(item.role, CHAT_ROLES, `${context}[${index}].role`);
+        assertString(item.content, `${context}[${index}].content`);
+    });
+}
+function assertUsage(value, context) {
+    assertObject(value, context);
+    assertAllowedKeys(value, ["prompt_tokens", "completion_tokens", "total_tokens"], context);
+    for (const key of ["prompt_tokens", "completion_tokens", "total_tokens"]) {
+        const candidate = value[key];
+        if (candidate !== undefined &&
+            (!Number.isInteger(candidate) || candidate < 0)) {
+            throw new Error(`${context}.${key} must be a non-negative integer`);
+        }
+    }
+}
+export function assertArtifactRefV1(value) {
+    assertObject(value, "artifact-ref.v1");
+    assertMetadata(value, "artifact-ref.v1");
+    assertArtifact(value, "artifact-ref.v1", true);
+}
+export function assertModelCallRecordV1(value) {
+    assertObject(value, "model-call-record.v1");
+    assertAllowedKeys(value, [
+        "schema",
+        "schema_version",
+        "schema_bundle_hash",
+        "producer",
+        "producer_version",
+        "producer_git_sha",
+        "created_at",
+        "call_id",
+        "endpoint_id",
+        "provider_request_id",
+        "model",
+        "request_hash",
+        "response_hash",
+        "messages",
+        "status",
+        "side_effects",
+        "started_at",
+        "finished_at",
+        "latency_ms",
+        "usage",
+        "output_text",
+        "error",
+        "metadata"
+    ], "model-call-record.v1");
+    assertMetadata(value, "model-call-record.v1");
+    assertString(value.call_id, "call_id");
+    assertString(value.endpoint_id, "endpoint_id");
+    assertOptionalString(value.provider_request_id, "provider_request_id");
+    assertString(value.model, "model");
+    assertHash(value.request_hash, "request_hash");
+    if (value.response_hash !== undefined)
+        assertHash(value.response_hash, "response_hash");
+    assertChatMessages(value.messages, "messages");
+    assertStatus(value.status, "status");
+    assertSideEffects(value.side_effects, "side_effects");
+    assertDateTime(value.started_at, "started_at");
+    if (value.finished_at !== undefined)
+        assertDateTime(value.finished_at, "finished_at");
+    assertOptionalNumber(value.latency_ms, "latency_ms");
+    if (value.usage !== undefined)
+        assertUsage(value.usage, "usage");
+    assertOptionalString(value.output_text, "output_text");
+    if (value.error !== undefined)
+        assertError(value.error, "error");
+    if (value.metadata !== undefined)
+        assertObject(value.metadata, "metadata");
+}
+export function assertHarnessRunRequestV1(value) {
+    assertObject(value, "harness-run-request.v1");
+    assertAllowedKeys(value, [
+        "schema",
+        "schema_version",
+        "schema_bundle_hash",
+        "producer",
+        "producer_version",
+        "producer_git_sha",
+        "created_at",
+        "request_id",
+        "harness_kind",
+        "source_repo",
+        "base_git_sha",
+        "prompt",
+        "prompt_hash",
+        "allowed_tools",
+        "side_effects",
+        "requested_capabilities",
+        "metadata"
+    ], "harness-run-request.v1");
+    assertMetadata(value, "harness-run-request.v1");
+    assertString(value.request_id, "request_id");
+    assertHarnessKind(value.harness_kind, "harness_kind");
+    assertString(value.source_repo, "source_repo");
+    assertGitSha(value.base_git_sha, "base_git_sha");
+    assertString(value.prompt, "prompt");
+    assertHash(value.prompt_hash, "prompt_hash");
+    if (value.allowed_tools !== undefined)
+        assertStringArray(value.allowed_tools, "allowed_tools");
+    assertSideEffects(value.side_effects, "side_effects");
+    assertCapabilityMap(value.requested_capabilities, "requested_capabilities");
+    if (value.metadata !== undefined)
+        assertObject(value.metadata, "metadata");
+}
+export function assertHarnessRunResultV1(value) {
+    assertObject(value, "harness-run-result.v1");
+    assertAllowedKeys(value, [
+        "schema",
+        "schema_version",
+        "schema_bundle_hash",
+        "producer",
+        "producer_version",
+        "producer_git_sha",
+        "created_at",
+        "result_id",
+        "request_id",
+        "harness_kind",
+        "status",
+        "candidate_ids",
+        "output_summary",
+        "artifacts",
+        "capabilities",
+        "started_at",
+        "finished_at",
+        "errors",
+        "metadata"
+    ], "harness-run-result.v1");
+    assertMetadata(value, "harness-run-result.v1");
+    assertString(value.result_id, "result_id");
+    assertString(value.request_id, "request_id");
+    assertHarnessKind(value.harness_kind, "harness_kind");
+    assertStatus(value.status, "status");
+    assertStringArray(value.candidate_ids, "candidate_ids");
+    assertOptionalString(value.output_summary, "output_summary");
+    if (value.artifacts !== undefined)
+        assertArtifacts(value.artifacts, "artifacts");
+    assertCapabilityMap(value.capabilities, "capabilities");
+    assertDateTime(value.started_at, "started_at");
+    if (value.finished_at !== undefined)
+        assertDateTime(value.finished_at, "finished_at");
+    if (value.errors !== undefined) {
+        if (!Array.isArray(value.errors))
+            throw new Error("errors must be an array");
+        value.errors.forEach((error, index) => assertError(error, `errors[${index}]`));
+    }
+    if (value.metadata !== undefined)
+        assertObject(value.metadata, "metadata");
+}
+export function assertHarnessCandidateRecordV1(value) {
+    assertObject(value, "harness-candidate-record.v1");
+    assertAllowedKeys(value, [
+        "schema",
+        "schema_version",
+        "schema_bundle_hash",
+        "producer",
+        "producer_version",
+        "producer_git_sha",
+        "created_at",
+        "candidate_id",
+        "request_id",
+        "harness_kind",
+        "model_call_id",
+        "status",
+        "side_effects",
+        "branch_name",
+        "worktree_path",
+        "artifacts",
+        "score",
+        "error",
+        "metadata"
+    ], "harness-candidate-record.v1");
+    assertMetadata(value, "harness-candidate-record.v1");
+    assertString(value.candidate_id, "candidate_id");
+    assertString(value.request_id, "request_id");
+    assertHarnessKind(value.harness_kind, "harness_kind");
+    assertOptionalString(value.model_call_id, "model_call_id");
+    assertStatus(value.status, "status");
+    assertSideEffects(value.side_effects, "side_effects");
+    assertOptionalString(value.branch_name, "branch_name");
+    assertOptionalString(value.worktree_path, "worktree_path");
+    if (value.artifacts !== undefined)
+        assertArtifacts(value.artifacts, "artifacts");
+    assertOptionalNumber(value.score, "score");
+    if (value.error !== undefined)
+        assertError(value.error, "error");
+    if (value.metadata !== undefined)
+        assertObject(value.metadata, "metadata");
+}
+export function assertJudgeSynthesisRecordV1(value) {
+    assertObject(value, "judge-synthesis-record.v1");
+    assertAllowedKeys(value, [
+        "schema",
+        "schema_version",
+        "schema_bundle_hash",
+        "producer",
+        "producer_version",
+        "producer_git_sha",
+        "created_at",
+        "synthesis_id",
+        "judge_model_call_id",
+        "input_candidate_ids",
+        "status",
+        "decision",
+        "selected_candidate_id",
+        "rationale",
+        "final_output",
+        "score",
+        "metrics"
+    ], "judge-synthesis-record.v1");
+    assertMetadata(value, "judge-synthesis-record.v1");
+    assertString(value.synthesis_id, "synthesis_id");
+    assertOptionalString(value.judge_model_call_id, "judge_model_call_id");
+    assertStringArray(value.input_candidate_ids, "input_candidate_ids", 1);
+    assertStatus(value.status, "status");
+    assertEnum(value.decision, JUDGE_DECISIONS, "decision");
+    assertOptionalString(value.selected_candidate_id, "selected_candidate_id");
+    assertOptionalString(value.rationale, "rationale");
+    assertString(value.final_output, "final_output");
+    assertOptionalNumber(value.score, "score");
+    if (value.metrics !== undefined)
+        assertObject(value.metrics, "metrics");
+}
+export function assertBenchmarkTaskRecordV1(value) {
+    assertObject(value, "benchmark-task-record.v1");
+    assertAllowedKeys(value, [
+        "schema",
+        "schema_version",
+        "schema_bundle_hash",
+        "producer",
+        "producer_version",
+        "producer_git_sha",
+        "created_at",
+        "task_id",
+        "task_kind",
+        "source_repo",
+        "source_sha",
+        "prompt",
+        "prompt_hash",
+        "setup_hash",
+        "expected_evidence",
+        "scorer",
+        "holdout",
+        "contamination_notes",
+        "allowed_tools"
+    ], "benchmark-task-record.v1");
+    assertMetadata(value, "benchmark-task-record.v1");
+    assertString(value.task_id, "task_id");
+    assertEnum(value.task_kind, BENCHMARK_TASK_KINDS, "task_kind");
+    assertEnum(value.source_repo, BENCHMARK_SOURCE_REPOS, "source_repo");
+    assertGitSha(value.source_sha, "source_sha");
+    assertOptionalString(value.prompt, "prompt");
+    assertHash(value.prompt_hash, "prompt_hash");
+    assertHash(value.setup_hash, "setup_hash");
+    assertStringArray(value.expected_evidence, "expected_evidence", 1);
+    assertObject(value.scorer, "scorer");
+    assertAllowedKeys(value.scorer, ["kind", "params"], "scorer");
+    assertEnum(value.scorer.kind, BENCHMARK_SCORER_KINDS, "scorer.kind");
+    if (value.scorer.params !== undefined)
+        assertObject(value.scorer.params, "scorer.params");
+    assertBoolean(value.holdout, "holdout");
+    assertString(value.contamination_notes, "contamination_notes");
+    assertStringArray(value.allowed_tools, "allowed_tools");
+}
+export function assertToolCallPlanV1(value) {
+    assertObject(value, "tool-call-plan.v1");
+    assertAllowedKeys(value, [
+        "schema",
+        "schema_version",
+        "schema_bundle_hash",
+        "producer",
+        "producer_version",
+        "producer_git_sha",
+        "created_at",
+        "plan_id",
+        "tool_name",
+        "arguments_hash",
+        "side_effects",
+        "status"
+    ], "tool-call-plan.v1");
+    assertMetadata(value, "tool-call-plan.v1");
+    assertString(value.plan_id, "plan_id");
+    assertString(value.tool_name, "tool_name");
+    assertHash(value.arguments_hash, "arguments_hash");
+    assertSideEffects(value.side_effects, "side_effects");
+    assertStatus(value.status, "status");
+}
+export function assertToolExecutionRecordV1(value) {
+    assertObject(value, "tool-execution-record.v1");
+    assertAllowedKeys(value, [
+        "schema",
+        "schema_version",
+        "schema_bundle_hash",
+        "producer",
+        "producer_version",
+        "producer_git_sha",
+        "created_at",
+        "execution_id",
+        "plan_id",
+        "status",
+        "output_hash",
+        "error"
+    ], "tool-execution-record.v1");
+    assertMetadata(value, "tool-execution-record.v1");
+    assertString(value.execution_id, "execution_id");
+    assertString(value.plan_id, "plan_id");
+    assertStatus(value.status, "status");
+    if (value.output_hash !== undefined)
+        assertHash(value.output_hash, "output_hash");
+    if (value.error !== undefined)
+        assertError(value.error, "error");
+}
+export function assertEnsembleReceiptV1(value) {
+    assertObject(value, "ensemble-receipt.v1");
+    assertAllowedKeys(value, [
+        "schema",
+        "schema_version",
+        "schema_bundle_hash",
+        "producer",
+        "producer_version",
+        "producer_git_sha",
+        "created_at",
+        "receipt_id",
+        "run_id",
+        "status",
+        "artifact_hashes"
+    ], "ensemble-receipt.v1");
+    assertMetadata(value, "ensemble-receipt.v1");
+    assertString(value.receipt_id, "receipt_id");
+    assertString(value.run_id, "run_id");
+    assertStatus(value.status, "status");
+    if (!Array.isArray(value.artifact_hashes)) {
+        throw new Error("artifact_hashes must be an array");
+    }
+    value.artifact_hashes.forEach((hash, index) => {
+        assertHash(hash, `artifact_hashes[${index}]`);
+    });
+}
+export function assertModelFusionRecord(value) {
+    assertObject(value, "model-fusion record");
+    switch (value.schema) {
+        case "model-call-record.v1":
+            assertModelCallRecordV1(value);
+            return;
+        case "harness-run-request.v1":
+            assertHarnessRunRequestV1(value);
+            return;
+        case "harness-run-result.v1":
+            assertHarnessRunResultV1(value);
+            return;
+        case "harness-candidate-record.v1":
+            assertHarnessCandidateRecordV1(value);
+            return;
+        case "judge-synthesis-record.v1":
+            assertJudgeSynthesisRecordV1(value);
+            return;
+        case "benchmark-task-record.v1":
+            assertBenchmarkTaskRecordV1(value);
+            return;
+        case "artifact-ref.v1":
+            assertArtifactRefV1(value);
+            return;
+        case "tool-call-plan.v1":
+            assertToolCallPlanV1(value);
+            return;
+        case "tool-execution-record.v1":
+            assertToolExecutionRecordV1(value);
+            return;
+        case "ensemble-receipt.v1":
+            assertEnsembleReceiptV1(value);
+            return;
+        default:
+            throw new Error(`unsupported model-fusion schema: ${String(value.schema)}`);
+    }
+}

package/dist/receipt-story.d.ts

@@ -0,0 +1,27 @@
+import type { ReceiptBundle, RunEvent, SessionIsolation } from "./types.js";
+export type EventSummary = {
+    tone: "plain" | "info" | "ok" | "warn" | "err";
+    label: string;
+    detail: string;
+};
+export type ReceiptStory = {
+    runId: string;
+    status: ReceiptBundle["receipt"]["status"];
+    actor: string;
+    agent: string;
+    isolation: SessionIsolation;
+    workspace: {
+        baseRef: string;
+        manifestHash: string;
+        diffHash: string;
+        artifactCount: number;
+    };
+    policyHash: string;
+    secrets: string[];
+    network: string[];
+    eventCount: number;
+    eventsHead: string;
+    verificationCommand: string;
+};
+export declare function summarizeRunEvent(event: RunEvent): EventSummary;
+export declare function buildReceiptStory(bundle: ReceiptBundle): ReceiptStory;