@martinloop/mcp 0.7.1 → 0.8.0

package/dist/vendor/core/swarm/parent-receipt.js

@@ -0,0 +1,489 @@
+import { createHash } from "node:crypto";
+import { SWARM_PARENT_RECEIPT_SCHEMA_VERSION, SWARM_SCHEMA_VERSION } from "../../contracts/index.js";
+export class SwarmParentReceiptError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SwarmParentReceiptError";
+        this.code = code;
+    }
+}
+export function buildParentSwarmReceipt(sealed) {
+    const { plan, events, artifacts } = sealed.model;
+    const outcome = sealed.index.outcome;
+    if (outcome.state === "running") {
+        throw new SwarmParentReceiptError("NON_TERMINAL_SWARM", "A running swarm cannot produce a parent receipt.");
+    }
+    const terminalOutcome = structuredClone(outcome);
+    if (sealed.index.swarmId !== plan.swarmId || sealed.index.planHash !== plan.planHash) {
+        throw new SwarmParentReceiptError("SEALED_MODEL_MISMATCH", "The sealed evidence model does not match its index.");
+    }
+    const blockedActions = projectBlockedActions(events);
+    const reassignments = projectReassignments(events);
+    const childReceipts = projectChildReceipts(sealed);
+    const globalEvent = [...events].reverse().find((event) => (event.type === "GLOBAL_VERIFIER_PASSED" || event.type === "GLOBAL_VERIFIER_FAILED"));
+    const integratedTreeHash = optionalText(globalEvent?.payload.integratedTreeHash);
+    const globalVerificationId = optionalText(globalEvent?.payload.verificationId);
+    const evidenceFiles = sealed.index.files.map((file) => structuredClone(file));
+    const evidenceBindings = projectEvidenceBindings(plan, events, sealed.model.artifacts);
+    const base = {
+        schemaVersion: SWARM_PARENT_RECEIPT_SCHEMA_VERSION,
+        swarmId: plan.swarmId,
+        planHash: plan.planHash,
+        objective: plan.parentContract.objective,
+        engine: structuredClone(plan.engine),
+        baselineCommit: plan.baselineCommit,
+        tasks: projectTerminalTasks(plan.tasks, events),
+        agents: projectTerminalAgents(plan.agents, events),
+        budget: structuredClone(plan.parentContract.budget),
+        budgetLedger: projectBudgetLedger(plan.parentContract.budget, events),
+        childReceipts,
+        blockedActions,
+        reassignments,
+        events: events.map((event) => structuredClone(event)),
+        evidenceIndexSha256: sha256(sealed.indexBytes),
+        evidenceFiles,
+        evidenceBindings,
+        ...(integratedTreeHash ? { integratedTreeHash } : {}),
+        ...(globalVerificationId ? { globalVerificationId } : {}),
+        parentOutcome: terminalOutcome,
+        taskVerificationState: globalEvent?.type === "GLOBAL_VERIFIER_PASSED"
+            ? "passed"
+            : globalEvent?.type === "GLOBAL_VERIFIER_FAILED" ? "failed" : "unknown",
+        sealedAt: sealed.index.sealedAt
+    };
+    const receiptSha256 = sha256(stableJson(base));
+    return {
+        ...base,
+        receiptId: `swarm-receipt-${receiptSha256.slice(0, 16)}`,
+        receiptSha256
+    };
+}
+function projectTerminalTasks(tasks, events) {
+    const projected = new Map(tasks.map((task) => [task.taskId, structuredClone(task)]));
+    for (const event of [...events].sort(bySequence)) {
+        if (!event.taskId)
+            continue;
+        const task = projected.get(event.taskId);
+        if (!task)
+            continue;
+        if (event.type === "TASK_REASSIGNED") {
+            const toAgentId = requiredText(event.payload.toAgentId, "INVALID_REASSIGNMENT_EVENT");
+            projected.set(event.taskId, { ...task, assignedAgentId: toAgentId });
+        }
+        else if (event.type === "CHILD_STARTED") {
+            projected.set(event.taskId, { ...task, status: "running" });
+        }
+        else if (event.type === "CHILD_VERIFIED") {
+            projected.set(event.taskId, { ...task, status: "accepted" });
+        }
+        else if (event.type === "CHILD_STOPPED") {
+            projected.set(event.taskId, { ...task, status: "stopped" });
+        }
+        else if (event.type === "CHILD_NEEDS_REVIEW") {
+            projected.set(event.taskId, { ...task, status: "needs_review" });
+        }
+    }
+    return tasks.map((task) => projected.get(task.taskId));
+}
+function projectTerminalAgents(agents, events) {
+    const projected = new Map(agents.map((agent) => [agent.agentId, structuredClone(agent)]));
+    for (const event of [...events].sort(bySequence)) {
+        if (!event.agentId)
+            continue;
+        const agent = projected.get(event.agentId);
+        if (!agent)
+            continue;
+        if (event.type === "CHILD_STARTED") {
+            projected.set(event.agentId, { ...agent, status: "running", ...(event.childRunId ? { childRunId: event.childRunId } : {}) });
+        }
+        else if (event.type === "CHILD_VERIFIED") {
+            projected.set(event.agentId, { ...agent, status: "verified", ...(event.childRunId ? { childRunId: event.childRunId } : {}) });
+        }
+        else if (event.type === "CHILD_STOPPED") {
+            projected.set(event.agentId, { ...agent, status: "stopped", ...(event.childRunId ? { childRunId: event.childRunId } : {}) });
+        }
+        else if (event.type === "CHILD_NEEDS_REVIEW") {
+            projected.set(event.agentId, { ...agent, status: "needs_review", ...(event.childRunId ? { childRunId: event.childRunId } : {}) });
+        }
+    }
+    return agents.map((agent) => projected.get(agent.agentId));
+}
+function projectBudgetLedger(budget, events) {
+    const projected = new Map();
+    const childLeaseIds = new Map();
+    for (const event of [...events].sort(bySequence)) {
+        const explicitLeaseId = optionalText(event.payload.leaseId);
+        if (explicitLeaseId && event.childRunId)
+            childLeaseIds.set(event.childRunId, explicitLeaseId);
+        const leaseId = explicitLeaseId ?? (event.childRunId ? childLeaseIds.get(event.childRunId) : undefined);
+        if (!leaseId)
+            continue;
+        const previous = projected.get(leaseId);
+        const reservedUsd = event.payload.reservedUsd === undefined
+            ? previous?.reservedUsd
+            : requiredNumber(event.payload.reservedUsd, "INVALID_CHILD_BUDGET_EVENT");
+        const reservedTokens = event.payload.reservedTokens === undefined
+            ? previous?.reservedTokens
+            : requiredNumber(event.payload.reservedTokens, "INVALID_CHILD_BUDGET_EVENT");
+        if (reservedUsd === undefined || reservedTokens === undefined) {
+            throw new SwarmParentReceiptError("INVALID_CHILD_BUDGET_EVENT", "Persisted budget evidence omits the reserved lease amount.");
+        }
+        const statusValue = event.payload.leaseState;
+        const status = statusValue === "settled" || statusValue === "overspent" || statusValue === "released" || statusValue === "reserved"
+            ? statusValue
+            : previous?.status ?? "reserved";
+        const actualUsd = optionalNumber(event.payload.actualUsd);
+        const actualTokens = optionalNumber(event.payload.actualTokens);
+        projected.set(leaseId, {
+            leaseId,
+            agentId: previous?.agentId ?? requiredText(event.agentId, "INVALID_CHILD_BUDGET_EVENT"),
+            taskId: previous?.taskId ?? requiredText(event.taskId, "INVALID_CHILD_BUDGET_EVENT"),
+            reservedUsd,
+            reservedTokens,
+            status,
+            ...(actualUsd !== undefined && actualTokens !== undefined
+                ? { actualUsage: { usd: actualUsd, tokens: actualTokens } }
+                : previous?.actualUsage ? { actualUsage: structuredClone(previous.actualUsage) } : {})
+        });
+    }
+    const leases = [...projected.values()];
+    return {
+        capUsd: budget.maxUsd,
+        ...(budget.maxTokens === undefined ? {} : { capTokens: budget.maxTokens }),
+        settledUsd: leases.reduce((sum, lease) => sum + (lease.actualUsage?.usd ?? 0), 0),
+        settledTokens: leases.reduce((sum, lease) => sum + (lease.actualUsage?.tokens ?? 0), 0),
+        leases
+    };
+}
+function projectEvidenceBindings(plan, events, artifacts) {
+    const admissions = [];
+    const rejections = [];
+    const conflicts = [];
+    const integration = [];
+    const globalVerification = [];
+    const cleanup = [];
+    for (const artifact of artifacts) {
+        const value = artifact.value;
+        const nestedDecision = isRecord(value.decision) ? value.decision : undefined;
+        const decision = nestedDecision ?? (typeof value.candidateId === "string" ? value : undefined);
+        const validDecision = decision ? isCanonicalDecision(decision, plan, events) : false;
+        if (validDecision && decision?.state === "admitted")
+            admissions.push(artifact.path);
+        if (validDecision && decision?.state === "rejected")
+            rejections.push(artifact.path);
+        if (validDecision && (isRecord(value.conflict) || decision?.reasonCode === "integration_conflict"))
+            conflicts.push(artifact.path);
+        if ((nestedDecision && decision && validDecision && isCanonicalIntegrationEvent(value.event, decision, plan, events))
+            || isCanonicalReconstruction(value, plan))
+            integration.push(artifact.path);
+        if (isCanonicalGlobalVerification(value, plan, events))
+            globalVerification.push(artifact.path);
+        if (isCanonicalCleanup(value, plan, artifacts))
+            cleanup.push(artifact.path);
+    }
+    return {
+        admissions: uniqueSorted(admissions),
+        rejections: uniqueSorted(rejections),
+        conflicts: uniqueSorted(conflicts),
+        integration: uniqueSorted(integration),
+        globalVerification: uniqueSorted(globalVerification),
+        cleanup: uniqueSorted(cleanup)
+    };
+}
+function isCanonicalDecision(value, plan, events) {
+    if (value.schemaVersion !== SWARM_SCHEMA_VERSION
+        || value.swarmId !== plan.swarmId
+        || value.baselineCommit !== plan.baselineCommit
+        || !isNonEmptyText(value.admissionId)
+        || typeof value.candidateId !== "string"
+        || !isNonEmptyText(value.workspaceId)
+        || !isNonEmptyText(value.childRunId)
+        || !isNonEmptyText(value.agentId)
+        || !isStringArray(value.taskIds, true)
+        || !isStringArray(value.changedPaths)
+        || !["admitted", "rejected"].includes(String(value.state))
+        || !SWARM_ADMISSION_REASON_CODES.has(String(value.reasonCode))
+        || (value.state === "admitted" && value.reasonCode !== "admitted")
+        || (value.state === "rejected" && value.reasonCode === "admitted")
+        || !RECEIPT_INTEGRITY_STATES.has(String(value.receiptIntegrity))
+        || (value.state === "admitted" && value.receiptIntegrity !== "verified")
+        || !isNonEmptyText(value.decidedAt)
+        || !isOptionalText(value.preIntegrationTreeHash)
+        || !isOptionalText(value.postIntegrationTreeHash)
+        || !isOptionalText(value.diagnostic))
+        return false;
+    const expectedTypes = value.state === "admitted"
+        ? ["CHILD_PATCH_ADMITTED"]
+        : value.reasonCode === "integration_conflict" ? ["INTEGRATION_CONFLICT"] : ["CHILD_PATCH_REJECTED"];
+    return events.some((event) => (expectedTypes.includes(event.type)
+        && event.payload.candidateId === value.candidateId
+        && event.swarmId === plan.swarmId
+        && event.planHash === plan.planHash
+        && event.parentPolicyVersion === plan.parentContract.policyVersion
+        && event.taskId !== undefined
+        && value.taskIds.includes(event.taskId)
+        && event.agentId === value.agentId
+        && event.childRunId === value.childRunId
+        && Number.isInteger(event.sequence)
+        && event.sequence > 0
+        && isNonEmptyText(event.idempotencyKey)
+        && isNonEmptyText(event.timestamp)));
+}
+function isCanonicalIntegrationEvent(candidateEvent, decision, plan, events) {
+    if (!isRecord(candidateEvent) || !isRecord(candidateEvent.payload))
+        return false;
+    const expectedType = decision.state === "admitted"
+        ? "CHILD_PATCH_ADMITTED"
+        : decision.reasonCode === "integration_conflict" ? "INTEGRATION_CONFLICT" : "CHILD_PATCH_REJECTED";
+    if (candidateEvent.type !== expectedType
+        || candidateEvent.swarmId !== plan.swarmId
+        || candidateEvent.parentPolicyVersion !== plan.parentContract.policyVersion
+        || candidateEvent.payload.candidateId !== decision.candidateId)
+        return false;
+    return events.some((event) => event.planHash === plan.planHash
+        && Number.isInteger(event.sequence)
+        && event.sequence > 0
+        && isNonEmptyText(event.idempotencyKey)
+        && stableJson(projectLiveEvent(event)) === stableJson(candidateEvent));
+}
+function isCanonicalReconstruction(value, plan) {
+    return value.schemaVersion === SWARM_SCHEMA_VERSION
+        && value.swarmId === plan.swarmId
+        && value.baselineCommit === plan.baselineCommit
+        && typeof value.reconstructionId === "string"
+        && typeof value.failedCandidateId === "string"
+        && typeof value.previousWorkspaceId === "string"
+        && typeof value.replacementWorkspaceId === "string"
+        && ["completed", "failed"].includes(String(value.state))
+        && (value.state !== "completed" || value.expectedTreeHash === value.actualTreeHash);
+}
+function isCanonicalGlobalVerification(value, plan, events) {
+    if (value.schemaVersion !== SWARM_SCHEMA_VERSION
+        || value.swarmId !== plan.swarmId
+        || value.parentPolicyVersion !== plan.parentContract.policyVersion
+        || value.baselineCommit !== plan.baselineCommit
+        || typeof value.verificationId !== "string"
+        || !isNonEmptyText(value.workspaceId)
+        || typeof value.integratedTreeHash !== "string"
+        || !isStringArray(value.commands)
+        || stableJson(value.commands) !== stableJson(plan.parentContract.globalVerifierStack.map((step) => step.command))
+        || !["pending", "passed", "failed", "unknown"].includes(String(value.commandState))
+        || !["pending", "clean", "mutated", "unknown"].includes(String(value.mutationState))
+        || !isNonEmptyText(value.startedAt)
+        || !isOptionalText(value.completedAt)
+        || (["passed", "failed"].includes(String(value.commandState)) && !isNonEmptyText(value.completedAt))
+        || !Array.isArray(value.subprocessResults)
+        || !value.subprocessResults.every(isCanonicalVerifierSubprocess))
+        return false;
+    const expectedType = value.commandState === "passed" && value.mutationState === "clean"
+        ? "GLOBAL_VERIFIER_PASSED"
+        : "GLOBAL_VERIFIER_FAILED";
+    const matching = events.filter((event) => ((event.type === "GLOBAL_VERIFIER_PASSED" || event.type === "GLOBAL_VERIFIER_FAILED")
+        && event.payload.verificationId === value.verificationId
+        && event.payload.integratedTreeHash === value.integratedTreeHash
+        && event.swarmId === plan.swarmId
+        && event.planHash === plan.planHash
+        && event.parentPolicyVersion === plan.parentContract.policyVersion
+        && Number.isInteger(event.sequence)
+        && event.sequence > 0
+        && isNonEmptyText(event.idempotencyKey)
+        && isNonEmptyText(event.timestamp)));
+    return matching.length === 1 && matching[0]?.type === expectedType;
+}
+function isCanonicalCleanup(value, plan, artifacts) {
+    if (value.schemaVersion !== SWARM_SCHEMA_VERSION
+        || value.swarmId !== plan.swarmId
+        || typeof value.cleanupId !== "string"
+        || typeof value.workspaceId !== "string"
+        || !["pending", "completed", "failed", "cleanup_pending"].includes(String(value.state))
+        || !["child", "integration", "verifier"].includes(String(value.workspaceKind))
+        || !["not_required", "pending", "closed", "failed"].includes(String(value.processCloseState))
+        || !["pending", "removed", "failed"].includes(String(value.removalState))
+        || typeof value.evidencePersisted !== "boolean"
+        || !isNonEmptyText(value.attemptedAt)
+        || !isOptionalText(value.completedAt)
+        || !isOptionalText(value.errorCode)
+        || (value.state === "completed" && (!isNonEmptyText(value.completedAt) || value.removalState !== "removed"))
+        || (value.state !== "completed" && !isNonEmptyText(value.errorCode)))
+        return false;
+    return artifacts.some((artifact) => {
+        const completionCleanup = artifact.value.cleanup;
+        return isRecord(completionCleanup)
+            && stableJson(completionCleanup) === stableJson(value);
+    });
+}
+function projectLiveEvent(event) {
+    return {
+        type: event.type,
+        swarmId: event.swarmId,
+        timestamp: event.timestamp,
+        parentPolicyVersion: event.parentPolicyVersion,
+        ...(event.taskId ? { taskId: event.taskId } : {}),
+        ...(event.agentId ? { agentId: event.agentId } : {}),
+        ...(event.childRunId ? { childRunId: event.childRunId } : {}),
+        ...(event.failureClass ? { failureClass: event.failureClass } : {}),
+        payload: structuredClone(event.payload)
+    };
+}
+function isCanonicalVerifierSubprocess(value) {
+    return isRecord(value)
+        && isNonEmptyText(value.command)
+        && typeof value.launched === "boolean"
+        && typeof value.completed === "boolean"
+        && typeof value.timedOut === "boolean"
+        && (value.exitCode === null || (typeof value.exitCode === "number" && Number.isInteger(value.exitCode)))
+        && isOptionalText(value.signal)
+        && isNonEmptyText(value.startedAt)
+        && isOptionalText(value.completedAt);
+}
+function isStringArray(value, requireNonEmpty = false) {
+    return Array.isArray(value)
+        && (!requireNonEmpty || value.length > 0)
+        && value.every((item) => isNonEmptyText(item));
+}
+function isNonEmptyText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isOptionalText(value) {
+    return value === undefined || isNonEmptyText(value);
+}
+const RECEIPT_INTEGRITY_STATES = new Set([
+    "verified", "unsigned", "tamper_detected", "relocated", "material_missing", "selector_noncanonical"
+]);
+const SWARM_ADMISSION_REASON_CODES = new Set([
+    "admitted", "child_not_terminal", "process_active", "identity_mismatch", "receipt_not_verified",
+    "receipt_scope_mismatch", "stale_baseline", "git_inventory_failed", "invalid_concrete_path", "unsafe_path",
+    "undeclared_path", "path_not_allowed", "path_denied", "task_scope_violation", "candidate_changed_during_capture",
+    "empty_candidate", "patch_hash_mismatch", "integration_precondition_failed", "integration_conflict",
+    "integration_apply_failed", "artifact_persistence_failed"
+]);
+function requiredNumber(value, code) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new SwarmParentReceiptError(code, "Persisted budget evidence is malformed.");
+    }
+    return value;
+}
+function optionalNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+export function verifyParentSwarmReceipt(receipt) {
+    if (receipt.schemaVersion !== SWARM_PARENT_RECEIPT_SCHEMA_VERSION) {
+        return { ok: false, reason: "UNKNOWN_RECEIPT_SCHEMA" };
+    }
+    try {
+        if (stableJson(receipt.blockedActions) !== stableJson(projectBlockedActions(receipt.events))) {
+            return { ok: false, reason: "BLOCKED_ACTION_PROJECTION_MISMATCH" };
+        }
+        if (stableJson(receipt.reassignments) !== stableJson(projectReassignments(receipt.events))) {
+            return { ok: false, reason: "REASSIGNMENT_PROJECTION_MISMATCH" };
+        }
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof SwarmParentReceiptError ? error.code : "INVALID_EVENT_PROJECTION" };
+    }
+    const { receiptId, receiptSha256, ...base } = receipt;
+    const expectedHash = sha256(stableJson(base));
+    if (receiptSha256 !== expectedHash || receiptId !== `swarm-receipt-${expectedHash.slice(0, 16)}`) {
+        return { ok: false, reason: "RECEIPT_HASH_MISMATCH" };
+    }
+    return { ok: true };
+}
+function projectBlockedActions(events) {
+    return events
+        .filter((event) => event.type === "ACTION_BLOCKED")
+        .map((event) => ({
+        eventId: requiredText(event.idempotencyKey, "INVALID_BLOCKED_ACTION_EVENT"),
+        sequence: event.sequence,
+        agentId: requiredText(event.agentId, "INVALID_BLOCKED_ACTION_EVENT"),
+        taskId: requiredText(event.taskId, "INVALID_BLOCKED_ACTION_EVENT"),
+        attemptId: requiredText(event.payload.attemptId, "INVALID_BLOCKED_ACTION_EVENT"),
+        action: requiredText(event.payload.action, "INVALID_BLOCKED_ACTION_EVENT"),
+        reason: requiredText(event.payload.reason, "INVALID_BLOCKED_ACTION_EVENT"),
+        timestamp: requiredText(event.timestamp, "INVALID_BLOCKED_ACTION_EVENT")
+    }))
+        .sort(bySequence);
+}
+function projectReassignments(events) {
+    return events
+        .filter((event) => event.type === "TASK_REASSIGNED")
+        .map((event) => ({
+        eventId: requiredText(event.idempotencyKey, "INVALID_REASSIGNMENT_EVENT"),
+        sequence: event.sequence,
+        taskId: requiredText(event.taskId, "INVALID_REASSIGNMENT_EVENT"),
+        fromAgentId: requiredText(event.payload.fromAgentId, "INVALID_REASSIGNMENT_EVENT"),
+        toAgentId: requiredText(event.payload.toAgentId, "INVALID_REASSIGNMENT_EVENT"),
+        fromAttemptId: requiredText(event.payload.fromAttemptId, "INVALID_REASSIGNMENT_EVENT"),
+        toAttemptId: requiredText(event.payload.toAttemptId, "INVALID_REASSIGNMENT_EVENT"),
+        reason: requiredText(event.payload.reason, "INVALID_REASSIGNMENT_EVENT"),
+        timestamp: requiredText(event.timestamp, "INVALID_REASSIGNMENT_EVENT")
+    }))
+        .sort(bySequence);
+}
+function projectChildReceipts(sealed) {
+    const startedChildRuns = new Set(sealed.model.events
+        .filter((event) => event.type === "CHILD_STARTED" && event.childRunId)
+        .map((event) => event.childRunId));
+    const terminalChildren = sealed.model.events.filter((event) => (event.childRunId
+        && startedChildRuns.has(event.childRunId)
+        && ["CHILD_VERIFIED", "CHILD_STOPPED", "CHILD_NEEDS_REVIEW"].includes(event.type)));
+    return terminalChildren.map((event) => {
+        const matches = sealed.model.artifacts.filter((artifact) => (artifact.path.startsWith("evidence/child-completions/") && artifact.value.childRunId === event.childRunId));
+        if (matches.length !== 1) {
+            throw new SwarmParentReceiptError("MISSING_CHILD_EVIDENCE", "Terminal child evidence must have one completion artifact.");
+        }
+        const value = matches[0].value;
+        const receipt = isRecord(value.receipt) ? value.receipt : undefined;
+        const integrity = receipt && isRecord(receipt.integrity) ? receipt.integrity : undefined;
+        if (integrity?.state !== "verified") {
+            throw new SwarmParentReceiptError("UNVERIFIED_CHILD_EVIDENCE", "Child receipt integrity must be verified.");
+        }
+        const childRunId = requiredText(value.childRunId, "INVALID_CHILD_EVIDENCE");
+        const integrityFile = sealed.index.files.find((file) => file.path === `${childRunId}/receipt-integrity.json`);
+        if (!integrityFile) {
+            throw new SwarmParentReceiptError("MISSING_CHILD_INTEGRITY_FILE", "Child receipt integrity material is absent from the sealed index.");
+        }
+        const taskIds = value.taskIds;
+        if (!Array.isArray(taskIds) || taskIds.some((taskId) => typeof taskId !== "string" || taskId.length === 0)) {
+            throw new SwarmParentReceiptError("INVALID_CHILD_EVIDENCE", "Child completion task IDs are malformed.");
+        }
+        return {
+            childRunId,
+            agentId: requiredText(value.agentId, "INVALID_CHILD_EVIDENCE"),
+            attemptId: requiredText(value.attemptId, "INVALID_CHILD_EVIDENCE"),
+            taskIds: [...taskIds],
+            receiptIntegritySha256: integrityFile.sha256
+        };
+    }).sort((left, right) => left.childRunId.localeCompare(right.childRunId));
+}
+function requiredText(value, code) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new SwarmParentReceiptError(code, "Persisted receipt evidence is missing required identity.");
+    }
+    return value;
+}
+function optionalText(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function bySequence(left, right) {
+    return left.sequence - right.sequence;
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function stableJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/vendor/core/swarm/receipt-projection.d.ts

@@ -0,0 +1,26 @@
+import type { SwarmParentReceipt } from "../../contracts/index.js";
+import { type SwarmReceiptIntegritySummary } from "../persistence/swarm-integrity.js";
+interface SwarmReceiptSealCommit {
+    schemaVersion: "martin.swarm-receipt-seal.v1";
+    swarmId: string;
+    planHash: string;
+    receiptSha256: string;
+    evidenceIndexSha256: string;
+    integrityMaterialSha256: string;
+    committedAt: string;
+    commitHmacSha256: string;
+}
+export interface SwarmReceiptProjection {
+    receipt: SwarmParentReceipt;
+    integrity: SwarmReceiptIntegritySummary;
+    seal: SwarmReceiptSealCommit;
+}
+export declare function readSwarmReceiptProjection(input: {
+    runsRoot: string;
+    swarmId: string;
+}): Promise<SwarmReceiptProjection>;
+export declare function verifySwarmReceiptProjection(input: {
+    runsRoot: string;
+    swarmId: string;
+}): Promise<SwarmReceiptIntegritySummary>;
+export {};

package/dist/vendor/core/swarm/receipt-projection.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { resolveSwarmReceiptIntegrityPath, verifySwarmReceiptSealCommitAuthentication, verifySwarmReceiptIntegrityFromFiles, } from "../persistence/swarm-integrity.js";
+import { readAndSealSwarmEvidence } from "./evidence.js";
+import { buildParentSwarmReceipt } from "./parent-receipt.js";
+import { assertSwarmPathIdentifier } from "./workspaces.js";
+export async function readSwarmReceiptProjection(input) {
+    assertSwarmPathIdentifier(input.swarmId, "swarm ID");
+    const runsRoot = await realpath(resolve(input.runsRoot));
+    const swarmsRoot = await realpath(join(runsRoot, "_swarms"));
+    assertContainedOrSame(runsRoot, swarmsRoot, "Swarm projection escaped the runs root.");
+    const swarmRoot = await realpath(join(swarmsRoot, input.swarmId));
+    assertStrictlyContained(swarmsRoot, swarmRoot, "Swarm projection escaped the swarm root.");
+    const evidenceRootExpected = join(swarmRoot, "evidence");
+    const evidenceRoot = await resolveExactDirectory(swarmRoot, evidenceRootExpected);
+    assertStrictlyContained(swarmRoot, evidenceRoot, "Swarm projection escaped the evidence root.");
+    const receiptPath = await resolveExactRegularFile(evidenceRoot, join(evidenceRoot, "parent-receipt.json"));
+    const indexPath = await resolveExactRegularFile(evidenceRoot, join(evidenceRoot, "evidence-index.json"));
+    const integrityPath = await resolveExactRegularFile(evidenceRoot, resolveSwarmReceiptIntegrityPath(runsRoot, input.swarmId));
+    const sealPath = await resolveExactRegularFile(evidenceRoot, join(evidenceRoot, "swarm-receipt-seal.json"));
+    for (const path of [receiptPath, indexPath, integrityPath, sealPath]) {
+        assertStrictlyContained(evidenceRoot, path, "Swarm projection artifact escaped the evidence root.");
+    }
+    const [receiptRaw, indexRaw, integrityRaw, sealRaw] = await Promise.all([
+        readFile(receiptPath, "utf8"),
+        readFile(indexPath, "utf8"),
+        readFile(integrityPath, "utf8"),
+        readFile(sealPath, "utf8")
+    ]);
+    const receipt = parseCommittedProjectionJson(receiptRaw, "parent receipt");
+    const seal = parseCommittedProjectionJson(sealRaw, "receipt seal");
+    if (seal.schemaVersion !== "martin.swarm-receipt-seal.v1"
+        || seal.swarmId !== input.swarmId
+        || seal.planHash !== receipt.planHash
+        || seal.receiptSha256 !== sha256Text(receiptRaw)
+        || seal.evidenceIndexSha256 !== sha256Text(indexRaw)
+        || seal.integrityMaterialSha256 !== sha256Text(integrityRaw)
+        || !await verifySwarmReceiptSealCommitAuthentication({
+            runsRoot,
+            swarmId: input.swarmId,
+            commit: seal
+        })) {
+        throw codedRuntimeError("SWARM_SEAL_COMMIT_MISMATCH", "Committed swarm receipt seal is missing or tampered.");
+    }
+    const integrity = await verifySwarmReceiptIntegrityFromFiles({ runsRoot, swarmId: input.swarmId });
+    if (integrity.state !== "verified") {
+        throw codedRuntimeError("SWARM_SEAL_INTEGRITY_FAILED", "Committed swarm receipt integrity did not verify.");
+    }
+    const canonical = await readAndSealSwarmEvidence({ rootDir: runsRoot, swarmId: input.swarmId });
+    const canonicalReceipt = buildParentSwarmReceipt(canonical);
+    if (receiptRaw !== `${JSON.stringify(canonicalReceipt, null, 2)}\n`) {
+        throw codedRuntimeError("SWARM_SEAL_COMMIT_MISMATCH", "Committed swarm receipt disagrees with canonical evidence.");
+    }
+    return { receipt, integrity, seal };
+}
+async function resolveExactDirectory(parent, expected) {
+    const metadata = await lstat(expected);
+    if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+        throw codedRuntimeError("SWARM_SEAL_PATH_ALIAS", "Swarm seal directory is not an exact canonical directory.");
+    }
+    const canonical = await realpath(expected);
+    assertStrictlyContained(parent, canonical, "Swarm seal directory escaped its parent.");
+    if (!sameFilesystemPath(canonical, resolve(expected))) {
+        throw codedRuntimeError("SWARM_SEAL_PATH_ALIAS", "Swarm seal directory is aliased.");
+    }
+    return canonical;
+}
+async function resolveExactRegularFile(parent, expected) {
+    const metadata = await lstat(expected);
+    if (metadata.isSymbolicLink() || !metadata.isFile()) {
+        throw codedRuntimeError("SWARM_SEAL_PATH_ALIAS", "Swarm seal artifact is not an exact regular file.");
+    }
+    const canonical = await realpath(expected);
+    assertStrictlyContained(parent, canonical, "Swarm seal artifact escaped its parent.");
+    if (!sameFilesystemPath(canonical, resolve(expected))) {
+        throw codedRuntimeError("SWARM_SEAL_PATH_ALIAS", "Swarm seal artifact is aliased.");
+    }
+    return canonical;
+}
+function sameFilesystemPath(left, right) {
+    return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+export async function verifySwarmReceiptProjection(input) {
+    try {
+        return (await readSwarmReceiptProjection(input)).integrity;
+    }
+    catch (error) {
+        return {
+            state: "tamper_detected",
+            reason: error instanceof Error && "code" in error ? String(error.code) : "swarm_seal_unavailable"
+        };
+    }
+}
+function sha256Text(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function assertContainedOrSame(parent, candidate, message) {
+    const relation = relative(parent, candidate);
+    if (relation === "")
+        return;
+    assertStrictlyContained(parent, candidate, message);
+}
+function assertStrictlyContained(parent, candidate, message) {
+    const relation = relative(parent, candidate);
+    if (!relation || relation === ".." || relation.startsWith(`..${sep}`) || isAbsolute(relation)) {
+        throw codedRuntimeError("LIVE_SWARM_PATH_ESCAPE", message);
+    }
+}
+function codedRuntimeError(code, message) {
+    return Object.assign(new Error(message), { code });
+}
+function parseCommittedProjectionJson(source, label) {
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        throw codedRuntimeError("MALFORMED_JSON", `Committed swarm ${label} is malformed.`);
+    }
+}