@martinloop/mcp 0.7.1 → 0.8.0

package/dist/vendor/core/swarm/hosted-export.js

@@ -0,0 +1,362 @@
+import { createHash, createHmac } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { SWARM_PARENT_RECEIPT_SCHEMA_VERSION, SWARM_SCHEMA_VERSION, computeSwarmLivePlanHash, } from "../../contracts/index.js";
+import { SWARM_EVIDENCE_INDEX_SCHEMA_VERSION, SWARM_HOSTED_SCHEMA_VERSION, canonicalSwarmHostedTransportBytes, computeSwarmHostedEnvelopeIdentity, validateSwarmHostedEnvelope, } from "../../contracts/swarm-hosted.js";
+import { readPrivateIntegrityKey } from "../persistence/integrity.js";
+import { readSwarmReceiptProjection } from "./receipt-projection.js";
+import { assertSwarmPathIdentifier } from "./workspaces.js";
+import { readSwarmOperationalState } from "./operations.js";
+export const SWARM_HOSTED_TRANSPORT_DOMAIN = "martin.swarm-hosted.v1";
+async function deriveSwarmHostedTransportKeyMaterialFromReceipt(input) {
+    assertSwarmPathIdentifier(input.swarmId, "swarm ID");
+    const runsRoot = await realpath(resolve(input.runsRoot));
+    const receiptSecret = await readPrivateIntegrityKey(runsRoot, `swarm-${input.swarmId}.key`);
+    if (!receiptSecret)
+        throw new Error("SWARM_SEAL_KEY_UNAVAILABLE");
+    const secret = createHmac("sha256", receiptSecret)
+        .update(`${input.domain}\n${input.swarmId}\n`)
+        .digest("hex");
+    return { secret, keyId: `hosted-${sha256(secret).slice(0, 16)}` };
+}
+const productionDependencies = {
+    readOperationalState: (input) => readSwarmOperationalState(input),
+    readReceiptProjection: (input) => readSwarmReceiptProjection(input),
+    ensureHostedTransportKey: deriveHostedTransportKeyMaterial,
+};
+/** @internal Direct-module seam for proving derivation never creates another secret file. */
+export async function deriveHostedTransportKeyMaterial(input) {
+    try {
+        return await deriveSwarmHostedTransportKeyMaterialFromReceipt({
+            ...input,
+            domain: SWARM_HOSTED_TRANSPORT_DOMAIN,
+        });
+    }
+    catch {
+        throw hostedError("SWARM_HOSTED_KEY_UNAVAILABLE", "Authenticated receipt key material is unavailable for hosted derivation.");
+    }
+}
+export async function buildSwarmHostedEnvelope(input) {
+    return buildSwarmHostedEnvelopeWithDependencies(input, productionDependencies);
+}
+export async function buildSwarmHostedEnvelopeWithDependencies(input, dependencies) {
+    const selector = { runsRoot: input.runsRoot, swarmId: input.swarmId };
+    const [operational, projection] = await Promise.all([
+        dependencies.readOperationalState(selector),
+        dependencies.readReceiptProjection(selector),
+    ]);
+    assertAuthenticatedSource(input, operational, projection);
+    const unsigned = projectEnvelope(input.runtimeVersion, operational, projection);
+    const key = await dependencies.ensureHostedTransportKey(selector);
+    const keyLocatorHash = sha256(`${SWARM_HOSTED_TRANSPORT_DOMAIN}\n${input.swarmId}\n${key.keyId}\n`);
+    const envelopeWithLocator = {
+        ...unsigned,
+        transportSignature: {
+            algorithm: "hmac-sha256",
+            keyId: key.keyId,
+            keyLocatorHash,
+            signatureHmacSha256: "0".repeat(64),
+        },
+    };
+    envelopeWithLocator.envelopeId = computeSwarmHostedEnvelopeIdentity(envelopeWithLocator);
+    const signatureHmacSha256 = createHmac("sha256", key.secret)
+        .update(`${SWARM_HOSTED_TRANSPORT_DOMAIN}\n${canonicalSwarmHostedTransportBytes(envelopeWithLocator)}`)
+        .digest("hex");
+    const envelope = {
+        ...envelopeWithLocator,
+        transportSignature: { ...envelopeWithLocator.transportSignature, signatureHmacSha256 },
+    };
+    const validation = validateSwarmHostedEnvelope(envelope);
+    if (!validation.ok) {
+        throw hostedError("SWARM_HOSTED_PROJECTION_INVALID", `Hosted swarm projection failed validation: ${validation.errors.map((error) => `${error.code}:${error.path}`).join(",")}`);
+    }
+    const canonicalBody = `${JSON.stringify(envelope)}\n`;
+    return {
+        envelope,
+        canonicalBody,
+        payloadSha256: sha256(canonicalBody),
+        envelopeIdentity: envelope.envelopeId,
+        transportKey: { keyId: key.keyId, keyLocatorHash, domain: SWARM_HOSTED_TRANSPORT_DOMAIN },
+    };
+}
+function projectEnvelope(runtimeVersion, operational, projection) {
+    const { plan } = operational;
+    const { receipt, integrity } = projection;
+    const childReceiptById = new Map(receipt.childReceipts.map((child) => [child.childRunId, child]));
+    const events = receipt.events.map((event) => projectEvent(event, childReceiptById));
+    const eventById = new Map(events.map((event) => [event.eventId, event]));
+    const plannedTaskAgent = new Map(plan.tasks.map((task) => [task.taskId, task.assignedAgentId]));
+    const effectiveTaskAgent = new Map(receipt.tasks.map((task) => [task.taskId, task.assignedAgentId]));
+    const agentTasks = new Map(receipt.agents.map((agent) => [agent.agentId, new Set(agent.contract.taskIds)]));
+    for (const task of receipt.tasks) {
+        for (const agentId of [plannedTaskAgent.get(task.taskId), effectiveTaskAgent.get(task.taskId)]) {
+            if (agentId)
+                agentTasks.get(agentId)?.add(task.taskId);
+        }
+    }
+    const agentById = new Map(receipt.agents.map((agent) => [agent.agentId, agent]));
+    const parentEvent = findSingleEvent(events, parentTerminalType(receipt.parentOutcome.state), undefined);
+    const globalEvent = receipt.globalVerificationId
+        ? findSingleEvent(events, receipt.taskVerificationState === "passed" ? "GLOBAL_VERIFIER_PASSED" : "GLOBAL_VERIFIER_FAILED", receipt.globalVerificationId)
+        : undefined;
+    const envelope = {
+        schemaVersion: SWARM_HOSTED_SCHEMA_VERSION,
+        envelopeId: "0".repeat(64),
+        sourceSchemas: {
+            swarm: SWARM_SCHEMA_VERSION,
+            receipt: SWARM_PARENT_RECEIPT_SCHEMA_VERSION,
+            evidenceIndex: SWARM_EVIDENCE_INDEX_SCHEMA_VERSION,
+        },
+        sourceIdentities: {
+            receiptId: receipt.receiptId,
+            receiptSha256: receipt.receiptSha256,
+            evidenceIndexSha256: receipt.evidenceIndexSha256,
+            eventChainSha256: integrity.eventChainHead,
+        },
+        runtimeVersion,
+        createdAt: receipt.sealedAt,
+        swarm: {
+            swarmId: receipt.swarmId,
+            workspaceId: plan.workspaceId,
+            projectId: plan.projectId,
+            planHash: receipt.planHash,
+            baselineCommit: receipt.baselineCommit,
+        },
+        topology: {
+            tasks: receipt.tasks.map((task) => ({
+                taskId: task.taskId,
+                required: task.required,
+                dependsOn: [...task.dependsOn],
+                ...(plannedTaskAgent.get(task.taskId) ? { plannedAgentId: plannedTaskAgent.get(task.taskId) } : {}),
+                ...(task.assignedAgentId ? { effectiveAgentId: task.assignedAgentId } : {}),
+                status: task.status,
+            })),
+            agents: receipt.agents.map((agent) => ({
+                agentId: agent.agentId,
+                role: agent.role,
+                status: agent.status,
+                taskIds: [...(agentTasks.get(agent.agentId) ?? [])].sort(),
+                ...(agent.childRunId ? { childRunId: agent.childRunId } : {}),
+            })),
+            children: receipt.childReceipts.map((child) => {
+                const agent = agentById.get(child.agentId);
+                const evidence = events
+                    .filter((event) => event.childRunId === child.childRunId
+                    && event.agentId === child.agentId
+                    && event.attemptId === child.attemptId
+                    && (event.taskId === undefined || child.taskIds.includes(event.taskId)))
+                    .map(eventReference);
+                return {
+                    childRunId: child.childRunId,
+                    agentId: child.agentId,
+                    attemptId: child.attemptId,
+                    taskIds: [...child.taskIds],
+                    status: agent?.status ?? "needs_review",
+                    receiptIntegrityState: "verified",
+                    evidence,
+                };
+            }),
+        },
+        budget: {
+            capUsd: receipt.budgetLedger.capUsd,
+            ...(receipt.budgetLedger.capTokens !== undefined ? { capTokens: receipt.budgetLedger.capTokens } : {}),
+            settledUsd: receipt.budgetLedger.settledUsd,
+            settledTokens: receipt.budgetLedger.settledTokens,
+        },
+        interventions: {
+            blockedActions: receipt.blockedActions.map((action) => ({
+                action: action.action,
+                reasonCode: action.reason,
+                taskId: action.taskId,
+                agentId: action.agentId,
+                attemptId: action.attemptId,
+                evidence: [{ eventId: action.eventId, sequence: action.sequence }],
+            })),
+            reassignments: receipt.reassignments.map((reassignment) => ({
+                taskId: reassignment.taskId,
+                fromAgentId: reassignment.fromAgentId,
+                toAgentId: reassignment.toAgentId,
+                fromAttemptId: reassignment.fromAttemptId,
+                toAttemptId: reassignment.toAttemptId,
+                reasonCode: reassignment.reason,
+                evidence: [{ eventId: reassignment.eventId, sequence: reassignment.sequence }],
+            })),
+        },
+        integration: {
+            admissions: integrationDecisions(events, "CHILD_PATCH_ADMITTED", "admitted"),
+            rejections: integrationDecisions(events, "CHILD_PATCH_REJECTED", "rejected"),
+            conflicts: integrationConflicts(events),
+            ...(receipt.integratedTreeHash ? { integratedTreeHash: receipt.integratedTreeHash } : {}),
+        },
+        events,
+        globalVerification: globalEvent ? {
+            state: receipt.taskVerificationState === "passed" ? "passed" : "failed",
+            verificationId: receipt.globalVerificationId,
+            ...(receipt.integratedTreeHash ? { integratedTreeHash: receipt.integratedTreeHash } : {}),
+            evidence: [eventReference(globalEvent)],
+        } : {
+            state: "unknown",
+            evidence: [],
+        },
+        parentOutcome: {
+            state: receipt.parentOutcome.state,
+            source: "sealed_parent_receipt",
+            evidence: [eventReference(parentEvent)],
+        },
+        taskVerificationState: receipt.taskVerificationState,
+        receiptIntegrityState: "verified",
+        transportSignature: {
+            algorithm: "hmac-sha256",
+            keyId: "pending",
+            keyLocatorHash: "0".repeat(64),
+            signatureHmacSha256: "0".repeat(64),
+        },
+    };
+    for (const reference of allEvidenceReferences(envelope)) {
+        if (!eventById.has(reference.eventId)) {
+            throw hostedError("SWARM_HOSTED_SOURCE_MISMATCH", "Hosted evidence reference does not resolve to an authenticated event.");
+        }
+    }
+    return envelope;
+}
+function assertAuthenticatedSource(input, operational, projection) {
+    const { plan, snapshot, events } = operational;
+    const { receipt, integrity, seal } = projection;
+    if (integrity.state !== "verified"
+        || !integrity.receiptSha256
+        || !integrity.evidenceIndexSha256
+        || !integrity.eventChainHead) {
+        throw hostedError("SWARM_HOSTED_INTEGRITY_NOT_VERIFIED", "Committed swarm receipt integrity is not verified.");
+    }
+    if (plan.schemaVersion !== SWARM_SCHEMA_VERSION
+        || receipt.schemaVersion !== SWARM_PARENT_RECEIPT_SCHEMA_VERSION
+        || seal.schemaVersion !== "martin.swarm-receipt-seal.v1") {
+        throw hostedError("SWARM_HOSTED_UNSUPPORTED_SOURCE", "Swarm hosted export source schema is unsupported.");
+    }
+    if (input.swarmId !== plan.swarmId
+        || computeSwarmLivePlanHash(plan) !== plan.planHash
+        || receipt.swarmId !== plan.swarmId
+        || seal.swarmId !== plan.swarmId
+        || receipt.planHash !== plan.planHash
+        || seal.planHash !== plan.planHash
+        || receipt.baselineCommit !== plan.baselineCommit
+        || receipt.evidenceIndexSha256 !== integrity.evidenceIndexSha256
+        || receipt.receiptSha256 !== integrity.receiptSha256
+        || integrity.taskVerificationState !== receipt.taskVerificationState
+        || seal.evidenceIndexSha256 !== receipt.evidenceIndexSha256
+        || seal.committedAt !== receipt.sealedAt
+        || snapshot.outcome.state !== receipt.parentOutcome.state
+        || stableJson(events) !== stableJson(receipt.events)) {
+        throw hostedError("SWARM_HOSTED_SOURCE_MISMATCH", "Committed swarm source identities disagree.");
+    }
+}
+function projectEvent(event, childReceiptById) {
+    const payload = event.payload;
+    const hasExplicitAttemptId = Object.prototype.hasOwnProperty.call(payload, "attemptId");
+    if (hasExplicitAttemptId
+        && (typeof payload.attemptId !== "string" || payload.attemptId.length === 0)) {
+        throw hostedError("SWARM_HOSTED_SOURCE_MISMATCH", "Present child attempt identity must be a non-empty string; only true omission may use receipt linkage.");
+    }
+    const explicitAttemptId = text(payload.attemptId)
+        ?? (event.type === "TASK_REASSIGNED" ? text(payload.fromAttemptId) : undefined);
+    let attemptId = explicitAttemptId;
+    if (event.childRunId && event.type.startsWith("CHILD_")) {
+        const child = childReceiptById.get(event.childRunId);
+        if (!child
+            || event.agentId !== child.agentId
+            || (event.taskId !== undefined && !child.taskIds.includes(event.taskId))
+            || (explicitAttemptId !== undefined && explicitAttemptId !== child.attemptId)) {
+            throw hostedError("SWARM_HOSTED_SOURCE_MISMATCH", "Child lifecycle event identities contradict authenticated child receipt linkage.");
+        }
+        attemptId = child.attemptId;
+    }
+    const relatedAttemptId = text(payload.toAttemptId);
+    const toAgentId = text(payload.toAgentId);
+    const candidateId = text(payload.candidateId);
+    const verificationId = text(payload.verificationId);
+    return {
+        eventId: event.idempotencyKey,
+        sourceIdempotencyKey: event.idempotencyKey,
+        sequence: event.sequence,
+        type: event.type,
+        timestamp: event.timestamp,
+        ...(event.taskId ? { taskId: event.taskId } : {}),
+        ...(event.agentId ? { agentId: event.type === "TASK_REASSIGNED" ? text(payload.fromAgentId) ?? event.agentId : event.agentId } : {}),
+        ...(event.childRunId ? { childRunId: event.childRunId } : {}),
+        ...(attemptId ? { attemptId } : {}),
+        ...(relatedAttemptId ? { relatedAttemptId } : {}),
+        ...(toAgentId ? { toAgentId } : {}),
+        ...(candidateId ? { candidateId } : {}),
+        ...(verificationId ? { verificationId } : {}),
+        ...(event.failureClass ? { failureClass: event.failureClass } : {}),
+    };
+}
+function integrationDecisions(events, type, state) {
+    return events.filter((event) => event.type === type).map((event) => {
+        if (!event.candidateId || !event.taskId || !event.agentId || !event.childRunId) {
+            throw hostedError("SWARM_HOSTED_SOURCE_MISMATCH", "Integration event lacks authenticated hosted identities.");
+        }
+        return {
+            candidateId: event.candidateId,
+            taskId: event.taskId,
+            agentId: event.agentId,
+            childRunId: event.childRunId,
+            state,
+            evidence: [eventReference(event)],
+        };
+    });
+}
+function integrationConflicts(events) {
+    return events.filter((event) => event.type === "INTEGRATION_CONFLICT").map((event) => ({
+        conflictId: event.candidateId ?? event.eventId,
+        taskIds: event.taskId ? [event.taskId] : [],
+        state: "blocking",
+        evidence: [eventReference(event)],
+    }));
+}
+function findSingleEvent(events, type, identity) {
+    const matches = events.filter((event) => event.type === type
+        && (identity === undefined || event.verificationId === identity));
+    if (matches.length !== 1) {
+        throw hostedError("SWARM_HOSTED_SOURCE_MISMATCH", `Expected one authoritative ${type} event.`);
+    }
+    return matches[0];
+}
+function parentTerminalType(state) {
+    return state === "verified" ? "SWARM_VERIFIED" : state === "stopped" ? "SWARM_STOPPED" : "SWARM_NEEDS_REVIEW";
+}
+function eventReference(event) {
+    return { eventId: event.eventId, sequence: event.sequence };
+}
+function allEvidenceReferences(envelope) {
+    return [
+        ...envelope.topology.children.flatMap((child) => child.evidence),
+        ...envelope.interventions.blockedActions.flatMap((action) => action.evidence),
+        ...envelope.interventions.reassignments.flatMap((reassignment) => reassignment.evidence),
+        ...envelope.integration.admissions.flatMap((decision) => decision.evidence),
+        ...envelope.integration.rejections.flatMap((decision) => decision.evidence),
+        ...envelope.integration.conflicts.flatMap((conflict) => conflict.evidence),
+        ...envelope.globalVerification.evidence,
+        ...envelope.parentOutcome.evidence,
+    ];
+}
+function text(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function sha256(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function hostedError(code, message) {
+    return Object.assign(new Error(`${code}: ${message}`), { code });
+}

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

@@ -0,0 +1,5 @@
+import { type SwarmAtlasView, type SwarmDashboardView, type SwarmSansaView } from "../../contracts/swarm-hosted.js";
+export type { SwarmAtlasView, SwarmDashboardView, SwarmSansaView, SwarmTraceFact } from "../../contracts/swarm-hosted.js";
+export declare function projectSwarmAtlasView(value: unknown): SwarmAtlasView;
+export declare function projectSwarmTraceFacts(value: unknown): SwarmSansaView;
+export declare function projectSwarmDashboardView(value: unknown): SwarmDashboardView;

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

@@ -0,0 +1,258 @@
+import { validateSwarmHostedEnvelope, } from "../../contracts/swarm-hosted.js";
+const FAILURE_EVENT_TYPES = new Set([
+    "CHILD_STOPPED",
+    "CHILD_NEEDS_REVIEW",
+    "CHILD_PATCH_REJECTED",
+]);
+const TERMINAL_EVENT_TYPES = {
+    stopped: "CHILD_STOPPED",
+    needs_review: "CHILD_NEEDS_REVIEW",
+    rejected: "CHILD_PATCH_REJECTED",
+};
+export function projectSwarmAtlasView(value) {
+    const envelope = validatedEnvelope(value);
+    return {
+        schemaVersion: "martin.swarm-atlas-view.v1",
+        envelopeId: envelope.envelopeId,
+        sourceIdentities: { ...envelope.sourceIdentities },
+        swarm: { ...envelope.swarm },
+        tasks: envelope.topology.tasks.map(cloneTask),
+        dependencyEdges: envelope.topology.tasks
+            .flatMap((task) => task.dependsOn.map((dependencyTaskId) => ({
+            fromTaskId: task.taskId,
+            toTaskId: dependencyTaskId,
+        })))
+            .sort(compareDependencyEdges),
+        agents: envelope.topology.agents.map((agent) => ({ ...agent, taskIds: [...agent.taskIds] })),
+        children: envelope.topology.children.map((child) => ({
+            ...child,
+            taskIds: [...child.taskIds],
+            evidence: cloneEvidence(child.evidence),
+        })),
+        budget: { ...envelope.budget },
+        interventions: {
+            blockedActions: envelope.interventions.blockedActions.map((action) => ({ ...action, evidence: cloneEvidence(action.evidence) })),
+            reassignments: envelope.interventions.reassignments.map((reassignment) => ({ ...reassignment, evidence: cloneEvidence(reassignment.evidence) })),
+        },
+        integration: {
+            ...envelope.integration,
+            admissions: envelope.integration.admissions.map((decision) => ({ ...decision, evidence: cloneEvidence(decision.evidence) })),
+            rejections: envelope.integration.rejections.map((decision) => ({ ...decision, evidence: cloneEvidence(decision.evidence) })),
+            conflicts: envelope.integration.conflicts.map((conflict) => ({ ...conflict, taskIds: [...conflict.taskIds], evidence: cloneEvidence(conflict.evidence) })),
+        },
+        globalVerification: { ...envelope.globalVerification, evidence: cloneEvidence(envelope.globalVerification.evidence) },
+        parentOutcome: { ...envelope.parentOutcome, evidence: cloneEvidence(envelope.parentOutcome.evidence) },
+        taskVerificationState: envelope.taskVerificationState,
+        receiptIntegrityState: envelope.receiptIntegrityState,
+    };
+}
+export function projectSwarmTraceFacts(value) {
+    const envelope = validatedEnvelope(value);
+    const facts = [
+        ...observedFacts(envelope),
+        ...recoveryFacts(envelope),
+        ...blockingDependencyFacts(envelope),
+    ].sort(compareFacts);
+    return {
+        schemaVersion: "martin.swarm-sansa-view.v1",
+        envelopeId: envelope.envelopeId,
+        sourceIdentities: { ...envelope.sourceIdentities },
+        facts,
+        parentOutcome: { ...envelope.parentOutcome, evidence: cloneEvidence(envelope.parentOutcome.evidence) },
+        globalVerification: { ...envelope.globalVerification, evidence: cloneEvidence(envelope.globalVerification.evidence) },
+    };
+}
+export function projectSwarmDashboardView(value) {
+    const envelope = validatedEnvelope(value);
+    return {
+        schemaVersion: "martin.swarm-dashboard-view.v1",
+        envelopeId: envelope.envelopeId,
+        sourceIdentities: { ...envelope.sourceIdentities },
+        swarmId: envelope.swarm.swarmId,
+        children: envelope.topology.children.map((child) => ({
+            ...child,
+            taskIds: [...child.taskIds],
+            evidence: cloneEvidence(child.evidence),
+        })),
+        parentOutcome: { ...envelope.parentOutcome, evidence: cloneEvidence(envelope.parentOutcome.evidence) },
+        globalVerification: { ...envelope.globalVerification, evidence: cloneEvidence(envelope.globalVerification.evidence) },
+        taskVerificationState: envelope.taskVerificationState,
+        receiptIntegrityState: envelope.receiptIntegrityState,
+        budget: { ...envelope.budget },
+    };
+}
+function validatedEnvelope(value) {
+    const validation = validateSwarmHostedEnvelope(value);
+    if (!validation.ok) {
+        const error = new Error(`INVALID_SWARM_HOSTED_ENVELOPE: ${validation.errors.map((item) => `${item.code}:${item.path}`).join(",")}`);
+        Object.assign(error, { code: "INVALID_SWARM_HOSTED_ENVELOPE" });
+        throw error;
+    }
+    return value;
+}
+function observedFacts(envelope) {
+    return envelope.events.flatMap((event) => {
+        if (FAILURE_EVENT_TYPES.has(event.type))
+            return [factFromEvent("failure", event)];
+        if (event.type === "TASK_REASSIGNED")
+            return [factFromEvent("reassignment", event)];
+        if (event.type === "GLOBAL_VERIFIER_PASSED" || event.type === "GLOBAL_VERIFIER_FAILED") {
+            return [factFromEvent("verification_boundary", event)];
+        }
+        return [];
+    });
+}
+function recoveryFacts(envelope) {
+    const facts = [];
+    for (const reassignment of envelope.interventions.reassignments) {
+        const task = envelope.topology.tasks.find((item) => item.taskId === reassignment.taskId);
+        if (task?.status !== "accepted" || task.effectiveAgentId !== reassignment.toAgentId)
+            continue;
+        const reassigned = referencedEvent(envelope.events, reassignment.evidence, "TASK_REASSIGNED");
+        if (!reassigned
+            || reassigned.taskId !== reassignment.taskId
+            || reassigned.agentId !== reassignment.fromAgentId
+            || reassigned.toAgentId !== reassignment.toAgentId
+            || reassigned.attemptId !== reassignment.fromAttemptId
+            || reassigned.relatedAttemptId !== reassignment.toAttemptId)
+            continue;
+        const failure = latestBefore(envelope.events, reassigned.sequence, (event) => FAILURE_EVENT_TYPES.has(event.type)
+            && event.taskId === reassignment.taskId
+            && event.agentId === reassignment.fromAgentId
+            && event.attemptId === reassignment.fromAttemptId);
+        const start = firstAfter(envelope.events, reassigned.sequence, (event) => event.type === "CHILD_STARTED"
+            && event.taskId === reassignment.taskId
+            && event.agentId === reassignment.toAgentId
+            && event.attemptId === reassignment.toAttemptId);
+        const completed = start && firstAfter(envelope.events, start.sequence, (event) => event.type === "CHILD_VERIFIED"
+            && event.taskId === reassignment.taskId
+            && event.agentId === reassignment.toAgentId
+            && event.attemptId === reassignment.toAttemptId
+            && event.childRunId === start.childRunId);
+        const admitted = completed && firstAfter(envelope.events, completed.sequence, (event) => event.type === "CHILD_PATCH_ADMITTED"
+            && event.taskId === reassignment.taskId
+            && event.agentId === reassignment.toAgentId
+            && event.attemptId === reassignment.toAttemptId
+            && event.childRunId === completed.childRunId);
+        const admission = admitted && envelope.integration.admissions.find((decision) => decision.taskId === reassignment.taskId
+            && decision.agentId === reassignment.toAgentId
+            && decision.childRunId === admitted.childRunId
+            && decision.candidateId === admitted.candidateId
+            && evidenceIncludes(decision.evidence, admitted));
+        if (!failure || !start || !completed || !admitted || !admission)
+            continue;
+        facts.push({
+            factId: `derived:recovery:${reassignment.taskId}:${reassignment.fromAttemptId}:${reassignment.toAttemptId}`,
+            kind: "recovery",
+            derivationKind: "deterministic_graph_derivation",
+            taskIds: [reassignment.taskId],
+            agentIds: [reassignment.fromAgentId, reassignment.toAgentId],
+            childRunIds: compactUnique([failure.childRunId, completed.childRunId]),
+            attemptIds: [reassignment.fromAttemptId, reassignment.toAttemptId],
+            verificationIds: [],
+            evidence: [failure, reassigned, start, completed, admitted].map(eventReference),
+        });
+    }
+    return facts;
+}
+function blockingDependencyFacts(envelope) {
+    const tasks = new Map(envelope.topology.tasks.map((task) => [task.taskId, task]));
+    const facts = [];
+    for (const task of [...envelope.topology.tasks].sort((left, right) => left.taskId.localeCompare(right.taskId))) {
+        if (!new Set(["queued", "ready", "running"]).has(task.status))
+            continue;
+        for (const path of terminalDependencyPaths(task.taskId, tasks)) {
+            const blocking = tasks.get(path.at(-1));
+            const terminalType = blocking && TERMINAL_EVENT_TYPES[blocking.status];
+            if (!blocking || !terminalType)
+                continue;
+            const terminal = [...envelope.events].reverse().find((event) => event.type === terminalType && event.taskId === blocking.taskId);
+            if (!terminal)
+                continue;
+            facts.push({
+                factId: `derived:blocking:${path.join("->")}`,
+                kind: "blocking_dependency",
+                derivationKind: "deterministic_graph_derivation",
+                taskIds: path,
+                agentIds: compactUnique([terminal.agentId]),
+                childRunIds: compactUnique([terminal.childRunId]),
+                attemptIds: compactUnique([terminal.attemptId]),
+                verificationIds: [],
+                evidence: [eventReference(terminal)],
+            });
+        }
+    }
+    return facts;
+}
+function terminalDependencyPaths(startTaskId, tasks) {
+    const paths = [];
+    const visit = (currentId, path, seen) => {
+        const current = tasks.get(currentId);
+        if (!current)
+            return;
+        for (const dependencyId of [...current.dependsOn].sort()) {
+            if (seen.has(dependencyId))
+                continue;
+            const dependency = tasks.get(dependencyId);
+            if (!dependency)
+                continue;
+            const next = [...path, dependencyId];
+            if (TERMINAL_EVENT_TYPES[dependency.status])
+                paths.push(next);
+            else
+                visit(dependencyId, next, new Set([...seen, dependencyId]));
+        }
+    };
+    visit(startTaskId, [startTaskId], new Set([startTaskId]));
+    return paths;
+}
+function factFromEvent(kind, event) {
+    return {
+        factId: `observed:${event.sequence}:${event.eventId}`,
+        kind,
+        derivationKind: "observed",
+        taskIds: compactUnique([event.taskId]),
+        agentIds: compactUnique([event.agentId, event.toAgentId]),
+        childRunIds: compactUnique([event.childRunId]),
+        attemptIds: compactUnique([event.attemptId, event.relatedAttemptId]),
+        verificationIds: compactUnique([event.verificationId]),
+        evidence: [eventReference(event)],
+    };
+}
+function referencedEvent(events, evidence, type) {
+    return evidence
+        .map((reference) => events.find((event) => event.eventId === reference.eventId && event.sequence === reference.sequence))
+        .find((event) => event?.type === type);
+}
+function latestBefore(events, sequence, predicate) {
+    return [...events].reverse().find((event) => event.sequence < sequence && predicate(event));
+}
+function firstAfter(events, sequence, predicate) {
+    return events.find((event) => event.sequence > sequence && predicate(event));
+}
+function evidenceIncludes(evidence, event) {
+    return evidence.some((reference) => reference.eventId === event.eventId && reference.sequence === event.sequence);
+}
+function eventReference(event) {
+    return { eventId: event.eventId, sequence: event.sequence };
+}
+function cloneEvidence(evidence) {
+    return evidence.map((reference) => ({ ...reference }));
+}
+function cloneTask(task) {
+    return { ...task, dependsOn: [...task.dependsOn] };
+}
+function compactUnique(values) {
+    return [...new Set(values.filter((value) => typeof value === "string"))];
+}
+function compareDependencyEdges(left, right) {
+    return left.fromTaskId.localeCompare(right.fromTaskId) || left.toTaskId.localeCompare(right.toTaskId);
+}
+function compareFacts(left, right) {
+    const leftSequence = left.evidence.at(-1)?.sequence ?? Number.MAX_SAFE_INTEGER;
+    const rightSequence = right.evidence.at(-1)?.sequence ?? Number.MAX_SAFE_INTEGER;
+    const derivationOrder = (fact) => fact.derivationKind === "observed" ? 0 : 1;
+    return leftSequence - rightSequence
+        || derivationOrder(left) - derivationOrder(right)
+        || left.factId.localeCompare(right.factId);
+}