@shapeshift-labs/frontier-swarm 0.5.21 → 0.5.23

package/dist/index.js

@@ -1,3 +1,5 @@
+import { createRunDashboardSnapshot, createRunEdgeEvent, createRunEvent, createRunNodeEvent, defineRunArtifact, defineRunAttempt, defineRunDecision, defineRunEvidence, defineRunLane, defineRunPatch, defineRunTask, defineRunVerification, linkRunNodes, replayRunEvents } from '@shapeshift-labs/frontier-run';
+import { acquireSemanticLease, createSemanticLeaseState, defineSemanticLeaseScope, validateSemanticLeaseFence } from '@shapeshift-labs/frontier-lease';
 export const FRONTIER_SWARM_MANIFEST_KIND = 'frontier.swarm.manifest';
 export const FRONTIER_SWARM_MANIFEST_VERSION = 1;
 export const FRONTIER_SWARM_TASK_KIND = 'frontier.swarm.task';
@@ -10,6 +12,22 @@ export const FRONTIER_SWARM_EVENT_KIND = 'frontier.swarm.event';
 export const FRONTIER_SWARM_EVENT_VERSION = 1;
 export const FRONTIER_SWARM_EVENT_STREAM_KIND = 'frontier.swarm.event-stream';
 export const FRONTIER_SWARM_EVENT_STREAM_VERSION = 1;
+export const FRONTIER_SWARM_RUN_GRAPH_KIND = 'frontier.swarm.run-graph';
+export const FRONTIER_SWARM_RUN_GRAPH_VERSION = 1;
+export const FRONTIER_SWARM_GRAPH_SNAPSHOT_KIND = 'frontier.swarm.graph-snapshot';
+export const FRONTIER_SWARM_GRAPH_SNAPSHOT_VERSION = 1;
+export const FRONTIER_SWARM_RUN_GRAPH_CHUNK_KIND = 'frontier.swarm.run-graph-chunk';
+export const FRONTIER_SWARM_RUN_GRAPH_CHUNK_VERSION = 1;
+export const FRONTIER_SWARM_GATE_RECORD_KIND = 'frontier.swarm.gate-record';
+export const FRONTIER_SWARM_GATE_RECORD_VERSION = 1;
+export const FRONTIER_SWARM_EVIDENCE_RECORD_KIND = 'frontier.swarm.evidence-record';
+export const FRONTIER_SWARM_EVIDENCE_RECORD_VERSION = 1;
+export const FRONTIER_SWARM_PATCH_EVENT_KIND = 'frontier.swarm.patch-event';
+export const FRONTIER_SWARM_PATCH_EVENT_VERSION = 1;
+export const FRONTIER_SWARM_REPLAY_RECORD_KIND = 'frontier.swarm.replay-record';
+export const FRONTIER_SWARM_REPLAY_RECORD_VERSION = 1;
+export const FRONTIER_SWARM_IMPROVEMENT_LOOP_KIND = 'frontier.swarm.improvement-loop';
+export const FRONTIER_SWARM_IMPROVEMENT_LOOP_VERSION = 1;
 export const FRONTIER_SWARM_MAILBOX_KIND = 'frontier.swarm.mailbox';
 export const FRONTIER_SWARM_MAILBOX_VERSION = 1;
 export const FRONTIER_SWARM_PROOF_KIND = 'frontier.swarm.proof';
@@ -30,6 +48,10 @@ export const FRONTIER_SWARM_MERGE_PLAN_KIND = 'frontier.swarm.merge-plan';
 export const FRONTIER_SWARM_MERGE_PLAN_VERSION = 1;
 export const FRONTIER_SWARM_MERGE_BUNDLE_KIND = 'frontier.swarm.merge-bundle';
 export const FRONTIER_SWARM_MERGE_BUNDLE_VERSION = 1;
+export const FRONTIER_SWARM_SEMANTIC_CHANGE_KIND = 'frontier.swarm.semantic-change';
+export const FRONTIER_SWARM_SEMANTIC_CHANGE_VERSION = 1;
+export const FRONTIER_SWARM_MERGE_CANDIDATE_KIND = 'frontier.swarm.merge-candidate';
+export const FRONTIER_SWARM_MERGE_CANDIDATE_VERSION = 1;
 export const FRONTIER_SWARM_QUEUE_OVERLAY_KIND = 'frontier.swarm.queue-overlay';
 export const FRONTIER_SWARM_QUEUE_OVERLAY_VERSION = 1;
 export const FRONTIER_SWARM_MERGE_INDEX_KIND = 'frontier.swarm.merge-index';
@@ -96,6 +118,8 @@ export const FRONTIER_SWARM_QUEUE_OUTCOME_MODEL_KIND = 'frontier.swarm.queue-out
 export const FRONTIER_SWARM_QUEUE_OUTCOME_MODEL_VERSION = 1;
 export const FRONTIER_SWARM_TERMINAL_STATE_RECONCILIATION_KIND = 'frontier.swarm.terminal-state-reconciliation';
 export const FRONTIER_SWARM_TERMINAL_STATE_RECONCILIATION_VERSION = 1;
+export const FRONTIER_SWARM_TERMINAL_OUTCOME_RECORD_KIND = 'frontier.swarm.terminal-outcome-record';
+export const FRONTIER_SWARM_TERMINAL_OUTCOME_RECORD_VERSION = 1;
 export const FRONTIER_SWARM_PRIORITY_POLICY_KIND = 'frontier.swarm.priority-policy';
 export const FRONTIER_SWARM_PRIORITY_POLICY_VERSION = 1;
 export const FRONTIER_SWARM_MODEL_ROUTE_KIND = 'frontier.swarm.model-route';
@@ -118,6 +142,42 @@ export const FRONTIER_SWARM_VERIFICATION_CATEGORY_HINTS = [
     'browser',
     'oracle'
 ];
+export const FRONTIER_SWARM_GRAPH_NODE_KINDS = [
+    'intent',
+    'task',
+    'worker',
+    'candidate',
+    'evidence',
+    'gate',
+    'decision',
+    'merge',
+    'replay',
+    'rsi'
+];
+export const FRONTIER_SWARM_GRAPH_EDGE_KINDS = [
+    'dependsOn',
+    'blocks',
+    'produces',
+    'verifies',
+    'conflictsWith',
+    'supersedes',
+    'mergesInto'
+];
+export const FRONTIER_SWARM_MERGE_CANDIDATE_ADMISSION_STATUSES = [
+    'safe',
+    'safe-with-losses',
+    'review-required',
+    'blocked'
+];
+export const FRONTIER_SWARM_MERGE_CANDIDATE_REASON_CODES = [
+    'missing-sidecar',
+    'empty-sidecar',
+    'stale-source-hash',
+    'symbol-conflict',
+    'effect-conflict',
+    'lossy-import',
+    'tests-missing'
+];
 export const FRONTIER_SWARM_SEMANTIC_OWNERSHIP_EXPORT_STABLE_KEY_KIND = 'exported-declaration';
 export const FRONTIER_SWARM_SEMANTIC_OWNERSHIP_NAMESPACE_EXPORT_STABLE_KEY_KIND = 'namespace-export';
 export const FRONTIER_SWARM_SEMANTIC_OWNERSHIP_TYPE_STABLE_KEY_KIND = 'type-declaration';
@@ -176,6 +236,7 @@ export const FRONTIER_SWARM_TERMINAL_OUTCOME_LABELS = [
     'superseded',
     'evidence-only',
     'no-change',
+    'research-complete',
     'generated-by-collector',
     'patch-missing',
     'bundle-missing',
@@ -186,6 +247,26 @@ export const FRONTIER_SWARM_TERMINAL_OUTCOME_LABELS = [
     'human-blocked',
     'coordinator-review'
 ];
+export const FRONTIER_SWARM_TERMINAL_OUTCOME_STATUSES = [
+    'applied',
+    'rejected',
+    'superseded',
+    'no-change',
+    'conflict',
+    'human-needed',
+    'research-complete',
+    'rerun'
+];
+export const FRONTIER_SWARM_TERMINAL_OUTCOME_REASON_CODES = [
+    'accepted-by-admission',
+    'failed-verification',
+    'superseded-by-newer-output',
+    'no-effective-change',
+    'conflict-detected',
+    'human-decision-required',
+    'research-complete',
+    'stale-rerun-required'
+];
 const DEFAULT_COMPLETED_STATUSES = ['completed', 'verified', 'done', 'verified-local-harness'];
 const DEFAULT_SWARM_EVENT_TYPES = [
     'swarm.started',
@@ -378,6 +459,1016 @@ export function createSwarmTaskSelection(manifestInput, taskInput, options = {})
         summary: summarizeTaskSelection(entries)
     };
 }
+export function createSwarmRunGraph(input = {}) {
+    const generatedAt = input.generatedAt ?? Date.now();
+    const nodes = dedupeGraphNodes((input.nodes ?? []).map((node) => normalizeGraphNode(node, generatedAt)));
+    const knownNodeIds = new Set(nodes.map((node) => node.id));
+    const edges = dedupeGraphEdges((input.edges ?? [])
+        .map((edge) => normalizeGraphEdge(edge, generatedAt))
+        .filter((edge) => knownNodeIds.has(edge.from) && knownNodeIds.has(edge.to)));
+    const knownEdgeIds = new Set(edges.map((edge) => edge.id));
+    const events = (input.events ?? [])
+        .map((event) => normalizeGraphEvent(event, generatedAt))
+        .filter((event) => event.nodeId === undefined || knownNodeIds.has(event.nodeId))
+        .filter((event) => event.edgeId === undefined || knownEdgeIds.has(event.edgeId))
+        .sort((left, right) => left.timestamp - right.timestamp || left.id.localeCompare(right.id));
+    const graph = {
+        kind: FRONTIER_SWARM_RUN_GRAPH_KIND,
+        version: FRONTIER_SWARM_RUN_GRAPH_VERSION,
+        id: input.id ?? 'swarm-run-graph:' + stableHash([input.runId, nodes.map((node) => node.id), edges.map((edge) => edge.id)]),
+        ...(input.runId ? { runId: input.runId } : {}),
+        ...(input.title ? { title: input.title } : {}),
+        generatedAt,
+        nodes,
+        edges,
+        events,
+        summary: summarizeSwarmRunGraph(nodes, edges, events),
+        ...(toJsonObject(input.metadata) ? { metadata: toJsonObject(input.metadata) } : {})
+    };
+    return graph;
+}
+export function normalizeSwarmRunGraph(input) {
+    if (input.kind === FRONTIER_SWARM_RUN_GRAPH_KIND) {
+        const graph = input;
+        return createSwarmRunGraph({
+            id: graph.id,
+            runId: graph.runId,
+            title: graph.title,
+            generatedAt: graph.generatedAt,
+            nodes: graph.nodes,
+            edges: graph.edges,
+            events: graph.events,
+            metadata: graph.metadata
+        });
+    }
+    return createSwarmRunGraph(input);
+}
+export function createSwarmGraphSnapshot(input) {
+    const graph = normalizeSwarmRunGraph(input.graph);
+    const generatedAt = input.generatedAt ?? Date.now();
+    return {
+        kind: FRONTIER_SWARM_GRAPH_SNAPSHOT_KIND,
+        version: FRONTIER_SWARM_GRAPH_SNAPSHOT_VERSION,
+        id: input.id ?? 'swarm-graph-snapshot:' + stableHash([graph.id, generatedAt, graph.summary]),
+        graphId: graph.id,
+        generatedAt,
+        summary: graph.summary,
+        graph,
+        ...(toJsonObject(input.metadata) ? { metadata: toJsonObject(input.metadata) } : {})
+    };
+}
+export function createSwarmGateRecord(input) {
+    const metrics = toJsonObject(input.metrics);
+    const metadata = toJsonObject(input.metadata);
+    return {
+        kind: FRONTIER_SWARM_GATE_RECORD_KIND,
+        version: FRONTIER_SWARM_GATE_RECORD_VERSION,
+        id: input.id ?? 'swarm-gate:' + stableHash([input.type, input.command, input.path, input.jobId, input.taskId, input.startedAt, input.finishedAt]),
+        type: input.type,
+        status: input.status ?? 'unknown',
+        required: input.required ?? false,
+        ...(input.command ? { command: input.command } : {}),
+        ...(input.path ? { path: input.path } : {}),
+        ...(input.jobId ? { jobId: input.jobId } : {}),
+        ...(input.taskId ? { taskId: input.taskId } : {}),
+        ...(input.startedAt !== undefined ? { startedAt: input.startedAt } : {}),
+        ...(input.finishedAt !== undefined ? { finishedAt: input.finishedAt } : {}),
+        ...(input.failureReason ? { failureReason: input.failureReason } : {}),
+        ...(input.confidence ? { confidence: input.confidence } : {}),
+        ...(metrics ? { metrics } : {}),
+        ...(metadata ? { metadata } : {})
+    };
+}
+export function createSwarmEvidenceRecord(input) {
+    const metrics = toJsonObject(input.metrics);
+    const metadata = toJsonObject(input.metadata);
+    const producedAt = input.producedAt ?? Date.now();
+    return {
+        kind: FRONTIER_SWARM_EVIDENCE_RECORD_KIND,
+        version: FRONTIER_SWARM_EVIDENCE_RECORD_VERSION,
+        id: input.id ?? 'swarm-evidence:' + stableHash([input.type, input.path, input.ref, input.jobId, input.taskId, input.gateId]),
+        type: input.type,
+        ...(input.path ? { path: input.path } : {}),
+        ...(input.ref ? { ref: input.ref } : {}),
+        ...(input.jobId ? { jobId: input.jobId } : {}),
+        ...(input.taskId ? { taskId: input.taskId } : {}),
+        ...(input.gateId ? { gateId: input.gateId } : {}),
+        producedAt,
+        ...(input.confidence ? { confidence: input.confidence } : {}),
+        ...(metrics ? { metrics } : {}),
+        ...(metadata ? { metadata } : {})
+    };
+}
+export function createSwarmPatchEvent(input) {
+    const generatedAt = input.generatedAt ?? Date.now();
+    const graphRefs = normalizeSwarmGraphRefs(input.graphRefs ?? []);
+    const sequence = input.sequence !== undefined ? Math.max(0, Math.floor(input.sequence)) : undefined;
+    return {
+        kind: FRONTIER_SWARM_PATCH_EVENT_KIND,
+        version: FRONTIER_SWARM_PATCH_EVENT_VERSION,
+        id: input.id ?? 'swarm-patch-event:' + stableHash([input.replayRecordId, sequence, input.operation, input.path, input.from, input.hash]),
+        operation: input.operation,
+        path: input.path,
+        ...(input.from ? { from: input.from } : {}),
+        ...(input.hash ? { hash: input.hash } : {}),
+        ...(sequence !== undefined ? { sequence } : {}),
+        ...(input.value !== undefined ? { value: toJsonValue(input.value) } : {}),
+        ...(input.before !== undefined ? { before: toJsonValue(input.before) } : {}),
+        ...(input.after !== undefined ? { after: toJsonValue(input.after) } : {}),
+        ...(input.jobId ? { jobId: input.jobId } : {}),
+        ...(input.taskId ? { taskId: input.taskId } : {}),
+        ...(input.replayRecordId ? { replayRecordId: input.replayRecordId } : {}),
+        graphRefs,
+        generatedAt,
+        ...(toJsonObject(input.metadata) ? { metadata: toJsonObject(input.metadata) } : {})
+    };
+}
+export function createSwarmReplayRecord(input = {}) {
+    const generatedAt = input.generatedAt ?? Date.now();
+    const title = input.title ?? titleFromId(input.id ?? input.subject ?? input.replayBundleId ?? 'replay record');
+    const evidenceRefs = normalizeNamedRefs(input.evidenceRefs ?? [], 'evidence');
+    const graphRefs = normalizeSwarmGraphRefs(input.graphRefs ?? []);
+    const replayId = input.id ?? 'swarm-replay-record:' + stableHash([
+        title,
+        input.status,
+        input.subject,
+        input.replayBundleId,
+        input.patchEvents ?? [],
+        evidenceRefs,
+        graphRefs,
+        input.jobId,
+        input.taskId
+    ]);
+    const patchEvents = (input.patchEvents ?? [])
+        .map((event, index) => normalizeSwarmPatchEvent(event, replayId, index))
+        .sort((left, right) => (left.sequence ?? Number.MAX_SAFE_INTEGER) - (right.sequence ?? Number.MAX_SAFE_INTEGER) || left.id.localeCompare(right.id));
+    return {
+        kind: FRONTIER_SWARM_REPLAY_RECORD_KIND,
+        version: FRONTIER_SWARM_REPLAY_RECORD_VERSION,
+        id: replayId,
+        title,
+        status: input.status ?? 'unknown',
+        ...(input.subject ? { subject: input.subject } : {}),
+        ...(input.replayBundleId ? { replayBundleId: input.replayBundleId } : {}),
+        patchEvents,
+        evidenceRefs,
+        graphRefs,
+        ...(input.jobId ? { jobId: input.jobId } : {}),
+        ...(input.taskId ? { taskId: input.taskId } : {}),
+        ...(input.startedAt !== undefined ? { startedAt: input.startedAt } : {}),
+        ...(input.finishedAt !== undefined ? { finishedAt: input.finishedAt } : {}),
+        generatedAt,
+        summary: {
+            patchEventCount: patchEvents.length,
+            evidenceRefCount: evidenceRefs.length,
+            graphRefCount: graphRefs.length
+        },
+        ...(toJsonObject(input.metadata) ? { metadata: toJsonObject(input.metadata) } : {})
+    };
+}
+export function createSwarmImprovementLoop(input = {}) {
+    const generatedAt = input.generatedAt ?? Date.now();
+    const title = input.title ?? titleFromId(input.id ?? input.subject ?? 'improvement loop');
+    const replayRecordIds = uniqueStrings(input.replayRecordIds ?? []);
+    const patchEventIds = uniqueStrings(input.patchEventIds ?? []);
+    const evidenceRefs = normalizeNamedRefs(input.evidenceRefs ?? [], 'evidence');
+    const graphRefs = normalizeSwarmGraphRefs(input.graphRefs ?? []);
+    return {
+        kind: FRONTIER_SWARM_IMPROVEMENT_LOOP_KIND,
+        version: FRONTIER_SWARM_IMPROVEMENT_LOOP_VERSION,
+        id: input.id ?? 'swarm-improvement-loop:' + stableHash([
+            title,
+            input.status,
+            input.subject,
+            input.observation,
+            input.action,
+            input.result,
+            replayRecordIds,
+            patchEventIds,
+            evidenceRefs,
+            graphRefs,
+            input.jobId,
+            input.taskId
+        ]),
+        title,
+        status: input.status ?? inferImprovementLoopStatus(input),
+        ...(input.subject ? { subject: input.subject } : {}),
+        ...(input.observation !== undefined ? { observation: toJsonValue(input.observation) } : {}),
+        ...(input.action !== undefined ? { action: toJsonValue(input.action) } : {}),
+        ...(input.result !== undefined ? { result: toJsonValue(input.result) } : {}),
+        replayRecordIds,
+        patchEventIds,
+        evidenceRefs,
+        graphRefs,
+        ...(input.jobId ? { jobId: input.jobId } : {}),
+        ...(input.taskId ? { taskId: input.taskId } : {}),
+        generatedAt,
+        summary: {
+            replayRecordCount: replayRecordIds.length,
+            patchEventCount: patchEventIds.length,
+            evidenceRefCount: evidenceRefs.length,
+            graphRefCount: graphRefs.length
+        },
+        ...(toJsonObject(input.metadata) ? { metadata: toJsonObject(input.metadata) } : {})
+    };
+}
+export function mapSwarmGateEvidenceToGraph(input) {
+    const generatedAt = input.generatedAt ?? Date.now();
+    const gateRecords = (input.gates ?? []).map((gate) => isSwarmGateRecord(gate) ? gate : createSwarmGateRecord(gate));
+    const evidenceRecords = (input.evidence ?? []).map((evidence) => isSwarmEvidenceRecord(evidence) ? evidence : createSwarmEvidenceRecord(evidence));
+    const nodes = [
+        ...gateRecords.map((gate) => ({
+            id: graphNodeId('gate', gate.id),
+            kind: 'gate',
+            title: gate.command ?? gate.path ?? gate.type,
+            status: gate.status,
+            jobId: gate.jobId,
+            taskId: gate.taskId,
+            path: gate.path,
+            generatedAt,
+            metadata: gate
+        })),
+        ...evidenceRecords.map((evidence) => ({
+            id: graphNodeId('evidence', evidence.id),
+            kind: 'evidence',
+            title: evidence.path ?? evidence.ref ?? evidence.type,
+            status: evidence.confidence,
+            jobId: evidence.jobId,
+            taskId: evidence.taskId,
+            path: evidence.path,
+            generatedAt,
+            metadata: evidence
+        }))
+    ];
+    const edges = [];
+    for (const evidence of evidenceRecords) {
+        if (evidence.gateId) {
+            edges.push({
+                kind: 'produces',
+                from: graphNodeId('gate', evidence.gateId),
+                to: graphNodeId('evidence', evidence.id),
+                generatedAt
+            });
+            edges.push({
+                kind: 'verifies',
+                from: graphNodeId('evidence', evidence.id),
+                to: graphNodeId('gate', evidence.gateId),
+                generatedAt
+            });
+        }
+    }
+    return createSwarmRunGraph({
+        runId: input.runId,
+        title: 'Gate and evidence graph',
+        generatedAt,
+        nodes,
+        edges
+    });
+}
+export function createSwarmGateEvidenceGraph(input) {
+    return mapSwarmGateEvidenceToGraph(input);
+}
+export function classifySwarmMergeCandidateAdmission(input = {}) {
+    const arrayInput = Array.isArray(input);
+    const objectInput = arrayInput
+        ? undefined
+        : input;
+    const status = objectInput ? normalizeOptionalString(objectInput.status) : undefined;
+    if (status)
+        return status;
+    const reasonCodes = arrayInput
+        ? normalizeSwarmMergeCandidateReasonCodes(input)
+        : normalizeSwarmMergeCandidateReasonCodes(objectInput?.reasonCodes ?? []);
+    if (reasonCodes.some((reason) => FRONTIER_SWARM_BLOCKING_MERGE_CANDIDATE_REASON_CODES.has(reason)))
+        return 'blocked';
+    if (reasonCodes.some((reason) => FRONTIER_SWARM_REVIEW_MERGE_CANDIDATE_REASON_CODES.has(reason)))
+        return 'review-required';
+    if (reasonCodes.includes('lossy-import'))
+        return 'safe-with-losses';
+    return 'safe';
+}
+export function createSwarmSemanticChange(input) {
+    if (isSwarmSemanticChange(input))
+        return cloneJsonValue(input);
+    const generatedAt = input.generatedAt ?? Date.now();
+    const symbolId = normalizeId(input.symbolId, 'semantic change symbol id');
+    const declarationKind = normalizeId(input.declarationKind, 'semantic change declaration kind');
+    const sourceSpan = normalizeSwarmSourceSpan(input.sourceSpan, {
+        sourcePath: input.sourcePath,
+        sourceHash: input.sourceHash,
+        expectedSourceHash: input.expectedSourceHash
+    });
+    const operation = normalizeOptionalString(input.operation) ?? 'unknown';
+    const derivedReasonCodes = deriveSwarmSemanticChangeReasonCodes(input, sourceSpan);
+    const reasonCodes = normalizeSwarmMergeCandidateReasonCodes([...(input.reasonCodes ?? []), ...derivedReasonCodes]);
+    const conflictReason = normalizeSwarmConflictReason(input.conflictReason, reasonCodes);
+    return {
+        kind: FRONTIER_SWARM_SEMANTIC_CHANGE_KIND,
+        version: FRONTIER_SWARM_SEMANTIC_CHANGE_VERSION,
+        id: input.id ?? 'swarm-semantic-change:' + stableHash([symbolId, declarationKind, sourceSpan, operation, reasonCodes]),
+        symbolId,
+        declarationKind,
+        sourceSpan,
+        operation,
+        confidence: normalizeSwarmSemanticConfidence(input.confidence),
+        ...(conflictReason ? { conflictReason } : {}),
+        status: classifySwarmMergeCandidateAdmission({ status: input.status, reasonCodes }),
+        reasonCodes,
+        generatedAt,
+        ...(toJsonObject(input.metadata) ? { metadata: toJsonObject(input.metadata) } : {})
+    };
+}
+export function createSwarmMergeCandidate(input) {
+    if (isSwarmMergeCandidate(input))
+        return cloneJsonValue(input);
+    const generatedAt = input.generatedAt ?? Date.now();
+    const shorthandChange = input.symbolId || input.declarationKind || input.operation || input.sourceSpan || input.sourcePath
+        ? [{
+                symbolId: input.symbolId ?? 'unknown-symbol',
+                declarationKind: input.declarationKind ?? 'unknown',
+                operation: input.operation ?? 'unknown',
+                sourceSpan: input.sourceSpan,
+                sourcePath: input.sourcePath,
+                sourceHash: input.sourceHash,
+                expectedSourceHash: input.expectedSourceHash,
+                confidence: input.confidence,
+                conflictReason: input.conflictReason,
+                status: input.status,
+                reasonCodes: input.reasonCodes,
+                generatedAt
+            }]
+        : [];
+    const semanticChanges = [...(input.semanticChanges ?? []), ...(input.changes ?? []), ...shorthandChange]
+        .map((change) => createSwarmSemanticChange({ ...change, generatedAt: change.generatedAt ?? generatedAt }));
+    const primaryChange = semanticChanges[0];
+    const candidateSourceSpan = primaryChange?.sourceSpan ?? normalizeSwarmSourceSpan(input.sourceSpan, {
+        sourcePath: input.sourcePath,
+        sourceHash: input.sourceHash,
+        expectedSourceHash: input.expectedSourceHash
+    });
+    const derivedReasonCodes = deriveSwarmMergeCandidateReasonCodes(input, semanticChanges, candidateSourceSpan);
+    const reasonCodes = normalizeSwarmMergeCandidateReasonCodes([
+        ...(input.reasonCodes ?? []),
+        ...semanticChanges.flatMap((change) => change.reasonCodes),
+        ...derivedReasonCodes
+    ]);
+    const symbolIds = uniqueStrings([
+        input.symbolId,
+        ...semanticChanges.map((change) => change.symbolId)
+    ]);
+    const declarationKinds = uniqueStrings([
+        input.declarationKind,
+        ...semanticChanges.map((change) => change.declarationKind)
+    ]);
+    const changedPaths = uniqueStrings(semanticChanges.map((change) => change.sourceSpan.path).concat(candidateSourceSpan.path));
+    const conflictReason = normalizeSwarmConflictReason(input.conflictReason, reasonCodes);
+    const metadata = toJsonObject(input.metadata);
+    return {
+        kind: FRONTIER_SWARM_MERGE_CANDIDATE_KIND,
+        version: FRONTIER_SWARM_MERGE_CANDIDATE_VERSION,
+        id: input.id ?? 'swarm-merge-candidate:' + stableHash([input.jobId, input.taskId, symbolIds, declarationKinds, semanticChanges, reasonCodes]),
+        ...(input.jobId ? { jobId: input.jobId } : {}),
+        ...(input.taskId ? { taskId: input.taskId } : {}),
+        ...(input.lane ? { lane: input.lane } : {}),
+        ...(input.title ? { title: input.title } : {}),
+        ...(input.sidecarPath ? { sidecarPath: input.sidecarPath } : {}),
+        symbolId: symbolIds[0] ?? primaryChange?.symbolId ?? 'unknown-symbol',
+        symbolIds,
+        declarationKind: declarationKinds[0] ?? primaryChange?.declarationKind ?? 'unknown',
+        declarationKinds,
+        sourceSpan: candidateSourceSpan,
+        operation: input.operation ?? primaryChange?.operation ?? 'unknown',
+        confidence: normalizeSwarmSemanticConfidence(input.confidence ?? primaryChange?.confidence),
+        ...(conflictReason ? { conflictReason } : {}),
+        status: classifySwarmMergeCandidateAdmission({ status: input.status, reasonCodes }),
+        reasonCodes,
+        semanticChanges,
+        changedPaths,
+        evidencePaths: uniqueStrings(input.evidencePaths ?? []),
+        generatedAt,
+        summary: {
+            changeCount: semanticChanges.length,
+            symbolCount: symbolIds.length,
+            reasonCount: reasonCodes.length
+        },
+        ...(metadata ? { metadata } : {})
+    };
+}
+export function mapSwarmMergeCandidatesToGraph(input) {
+    const generatedAt = input.generatedAt ?? Date.now();
+    const candidates = input.candidates.map((candidate) => createSwarmMergeCandidate({ ...candidate, generatedAt: candidate.generatedAt ?? generatedAt }));
+    const includeChangeNodes = input.includeChangeNodes !== false;
+    const nodes = [];
+    const edges = [];
+    for (const candidate of candidates) {
+        const candidateNodeId = graphNodeId('candidate', candidate.id);
+        nodes.push({
+            id: candidateNodeId,
+            kind: 'candidate',
+            title: candidate.title ?? candidate.symbolId,
+            status: candidate.status,
+            jobId: candidate.jobId,
+            taskId: candidate.taskId,
+            path: candidate.changedPaths[0],
+            generatedAt,
+            metadata: candidate
+        });
+        if (!includeChangeNodes)
+            continue;
+        for (const change of candidate.semanticChanges) {
+            const changeNodeId = graphNodeId('semantic-change', change.id);
+            nodes.push({
+                id: changeNodeId,
+                kind: 'semantic-change',
+                title: `${change.operation} ${change.symbolId}`,
+                status: change.status,
+                jobId: candidate.jobId,
+                taskId: candidate.taskId,
+                path: change.sourceSpan.path,
+                generatedAt,
+                metadata: change
+            });
+            edges.push({
+                kind: 'produces',
+                from: candidateNodeId,
+                to: changeNodeId,
+                label: 'semantic-change',
+                generatedAt,
+                metadata: {
+                    symbolId: change.symbolId,
+                    declarationKind: change.declarationKind,
+                    operation: change.operation,
+                    reasonCodes: change.reasonCodes
+                }
+            });
+            if (change.conflictReason) {
+                edges.push({
+                    kind: 'conflictsWith',
+                    from: candidateNodeId,
+                    to: changeNodeId,
+                    label: change.conflictReason,
+                    generatedAt
+                });
+            }
+        }
+    }
+    return { candidates, nodes, edges };
+}
+export function createSwarmMergeCandidateGraph(input) {
+    const generatedAt = input.generatedAt ?? Date.now();
+    const projection = mapSwarmMergeCandidatesToGraph({ ...input, generatedAt });
+    return createSwarmRunGraph({
+        id: input.id,
+        runId: input.runId,
+        title: input.title ?? 'Semantic merge candidate graph',
+        generatedAt,
+        nodes: projection.nodes,
+        edges: projection.edges,
+        metadata: input.metadata
+    });
+}
+export function mapSwarmReplayRecordsToGraph(input) {
+    const generatedAt = input.generatedAt ?? Date.now();
+    const replayRecords = (input.replayRecords ?? []).map((record) => isSwarmReplayRecord(record) ? record : createSwarmReplayRecord(record));
+    const nodes = [];
+    const edges = [];
+    for (const replay of replayRecords) {
+        const replayNodeId = graphNodeId('replay', replay.id);
+        nodes.push({
+            id: replayNodeId,
+            kind: 'replay',
+            title: replay.title,
+            status: replay.status,
+            jobId: replay.jobId,
+            taskId: replay.taskId,
+            generatedAt,
+            metadata: replay
+        });
+        for (const event of replay.patchEvents) {
+            const eventNodeId = graphNodeId('replay', event.id);
+            nodes.push({
+                id: eventNodeId,
+                kind: 'replay',
+                title: `${event.operation} ${event.path}`,
+                jobId: event.jobId ?? replay.jobId,
+                taskId: event.taskId ?? replay.taskId,
+                path: event.path,
+                generatedAt,
+                metadata: event
+            });
+            edges.push({
+                kind: 'produces',
+                from: replayNodeId,
+                to: eventNodeId,
+                label: event.operation,
+                generatedAt
+            });
+        }
+        for (const evidence of replay.evidenceRefs) {
+            const evidenceNodeId = graphNodeId('evidence', evidence.id);
+            nodes.push({
+                id: evidenceNodeId,
+                kind: 'evidence',
+                title: evidence.path ?? evidence.uri ?? evidence.id,
+                path: evidence.path,
+                generatedAt,
+                metadata: evidence
+            });
+            edges.push({
+                kind: 'verifies',
+                from: evidenceNodeId,
+                to: replayNodeId,
+                label: evidence.role ?? evidence.kind,
+                generatedAt
+            });
+        }
+    }
+    return createSwarmRunGraph({
+        runId: input.runId,
+        title: 'Replay records graph',
+        generatedAt,
+        nodes,
+        edges
+    });
+}
+export function createSwarmReplayRecordGraph(input) {
+    return mapSwarmReplayRecordsToGraph(input);
+}
+export function mapSwarmImprovementLoopsToGraph(input) {
+    const generatedAt = input.generatedAt ?? Date.now();
+    const loops = (input.improvementLoops ?? []).map((loop) => isSwarmImprovementLoop(loop) ? loop : createSwarmImprovementLoop(loop));
+    const nodes = [];
+    const edges = [];
+    for (const loop of loops) {
+        const phaseNodes = [];
+        if (loop.observation !== undefined) {
+            phaseNodes.push(createImprovementLoopPhaseNode(loop, 'observation', loop.observation, generatedAt));
+        }
+        if (loop.action !== undefined) {
+            phaseNodes.push(createImprovementLoopPhaseNode(loop, 'action', loop.action, generatedAt));
+        }
+        if (loop.result !== undefined) {
+            phaseNodes.push(createImprovementLoopPhaseNode(loop, 'result', loop.result, generatedAt));
+        }
+        if (phaseNodes.length === 0) {
+            phaseNodes.push({
+                id: graphNodeId('rsi', loop.id),
+                kind: 'rsi',
+                title: loop.title,
+                status: loop.status,
+                jobId: loop.jobId,
+                taskId: loop.taskId,
+                generatedAt,
+                metadata: loop
+            });
+        }
+        nodes.push(...phaseNodes);
+        for (let index = 1; index < phaseNodes.length; index += 1) {
+            edges.push({
+                kind: 'produces',
+                from: phaseNodes[index - 1].id,
+                to: phaseNodes[index].id,
+                label: index === 1 ? 'action' : 'result',
+                generatedAt
+            });
+        }
+        const entryNodeId = phaseNodes[0]?.id;
+        const exitNodeId = phaseNodes.at(-1)?.id;
+        for (const replayRecordId of loop.replayRecordIds) {
+            const replayNodeId = graphNodeId('replay', replayRecordId);
+            nodes.push({
+                id: replayNodeId,
+                kind: 'replay',
+                title: titleFromId(replayRecordId),
+                generatedAt,
+                metadata: { replayRecordId }
+            });
+            if (entryNodeId)
+                edges.push({ kind: 'produces', from: replayNodeId, to: entryNodeId, label: 'feeds-rsi', generatedAt });
+        }
+        for (const patchEventId of loop.patchEventIds) {
+            const patchNodeId = graphNodeId('replay', patchEventId);
+            nodes.push({
+                id: patchNodeId,
+                kind: 'replay',
+                title: titleFromId(patchEventId),
+                generatedAt,
+                metadata: { patchEventId }
+            });
+            if (entryNodeId)
+                edges.push({ kind: 'produces', from: patchNodeId, to: entryNodeId, label: 'feeds-rsi', generatedAt });
+        }
+        for (const evidence of loop.evidenceRefs) {
+            const evidenceNodeId = graphNodeId('evidence', evidence.id);
+            nodes.push({
+                id: evidenceNodeId,
+                kind: 'evidence',
+                title: evidence.path ?? evidence.uri ?? evidence.id,
+                path: evidence.path,
+                generatedAt,
+                metadata: evidence
+            });
+            if (exitNodeId)
+                edges.push({ kind: 'verifies', from: evidenceNodeId, to: exitNodeId, label: evidence.role ?? evidence.kind, generatedAt });
+        }
+    }
+    return createSwarmRunGraph({
+        runId: input.runId,
+        title: 'Improvement loop graph',
+        generatedAt,
+        nodes,
+        edges
+    });
+}
+export function createSwarmImprovementLoopGraph(input) {
+    return mapSwarmImprovementLoopsToGraph(input);
+}
+export function createSwarmRunGraphChunk(input = {}) {
+    const generatedAt = Date.now();
+    const nodes = dedupeGraphNodes((input.nodes ?? []).map((node) => normalizeGraphNode(node, generatedAt)));
+    const known = new Set(nodes.map((node) => node.id));
+    const edges = dedupeGraphEdges((input.edges ?? [])
+        .map((edge) => normalizeGraphEdge(edge, generatedAt))
+        .filter((edge) => known.has(edge.from) && known.has(edge.to)));
+    const entryNodeIds = uniqueStrings((input.entryNodeIds ?? []).filter((id) => known.has(id)));
+    const exitNodeIds = uniqueStrings((input.exitNodeIds ?? []).filter((id) => known.has(id)));
+    return {
+        kind: FRONTIER_SWARM_RUN_GRAPH_CHUNK_KIND,
+        version: FRONTIER_SWARM_RUN_GRAPH_CHUNK_VERSION,
+        id: input.id ?? 'swarm-run-graph-chunk:' + stableHash([nodes.map((node) => node.id), edges.map((edge) => edge.id), entryNodeIds, exitNodeIds]),
+        nodes,
+        edges,
+        entryNodeIds,
+        exitNodeIds,
+        summary: {
+            nodeCount: nodes.length,
+            edgeCount: edges.length,
+            entryCount: entryNodeIds.length,
+            exitCount: exitNodeIds.length
+        },
+        ...(toJsonObject(input.metadata) ? { metadata: toJsonObject(input.metadata) } : {})
+    };
+}
+export function createSwarmRunGraphChain(input) {
+    const nodes = input.nodes.map((node) => normalizeGraphNode(node));
+    const edges = [];
+    for (let index = 1; index < nodes.length; index += 1) {
+        edges.push({ kind: input.edgeKind ?? 'dependsOn', from: nodes[index - 1].id, to: nodes[index].id });
+    }
+    return createSwarmRunGraphChunk({
+        id: input.id,
+        nodes,
+        edges,
+        entryNodeIds: nodes[0] ? [nodes[0].id] : [],
+        exitNodeIds: nodes.at(-1) ? [nodes.at(-1).id] : [],
+        metadata: input.metadata
+    });
+}
+export function createSwarmRunGraphFork(input) {
+    const source = normalizeGraphNode(input.source);
+    const branches = input.branches.map((node) => normalizeGraphNode(node));
+    return createSwarmRunGraphChunk({
+        id: input.id,
+        nodes: [source, ...branches],
+        edges: branches.map((branch) => ({ kind: 'dependsOn', from: source.id, to: branch.id, label: 'fork' })),
+        entryNodeIds: [source.id],
+        exitNodeIds: branches.map((branch) => branch.id),
+        metadata: input.metadata
+    });
+}
+export function createSwarmRunGraphJoin(input) {
+    const branches = input.branches.map((node) => normalizeGraphNode(node));
+    const join = normalizeGraphNode(input.join);
+    return createSwarmRunGraphChunk({
+        id: input.id,
+        nodes: [...branches, join],
+        edges: branches.map((branch) => ({ kind: 'dependsOn', from: branch.id, to: join.id, label: 'join' })),
+        entryNodeIds: branches.map((branch) => branch.id),
+        exitNodeIds: [join.id],
+        metadata: input.metadata
+    });
+}
+export function createSwarmRunGraphBarrier(input) {
+    const prerequisites = input.prerequisites.map((node) => normalizeGraphNode(node));
+    const prerequisiteIds = prerequisites.map((node) => node.id);
+    const barrierMetadata = toJsonObject(input.barrier?.metadata);
+    const barrier = normalizeGraphNode({
+        ...(input.barrier ?? {}),
+        id: input.barrier?.id ?? (input.id ? `${input.id}:barrier` : graphNodeId('gate', 'barrier:' + stableHash(prerequisiteIds))),
+        kind: input.barrier?.kind ?? 'gate',
+        title: input.barrier?.title ?? 'Barrier',
+        metadata: {
+            ...(barrierMetadata ?? {}),
+            role: 'barrier',
+            graphChunkKind: 'barrier',
+            prerequisiteIds,
+            prerequisiteCount: prerequisiteIds.length
+        }
+    });
+    return createSwarmRunGraphChunk({
+        id: input.id,
+        nodes: [...prerequisites, barrier],
+        edges: prerequisites.map((node, index) => ({
+            kind: 'dependsOn',
+            from: node.id,
+            to: barrier.id,
+            label: 'barrier',
+            metadata: {
+                role: 'barrier-prerequisite',
+                barrierId: barrier.id,
+                prerequisiteId: node.id,
+                prerequisiteIndex: index,
+                prerequisiteCount: prerequisites.length
+            }
+        })),
+        entryNodeIds: prerequisiteIds,
+        exitNodeIds: [barrier.id],
+        metadata: input.metadata
+    });
+}
+export function createSwarmRunGraphRaceSelect(input) {
+    const baseBranches = input.branches.map((node) => normalizeGraphNode(node));
+    const branchIds = baseBranches.map((node) => node.id);
+    const selectedBranchId = input.selectedBranchId && branchIds.includes(input.selectedBranchId) ? input.selectedBranchId : undefined;
+    const rejectedBranchIds = new Set(selectedBranchId
+        ? branchIds.filter((id) => id !== selectedBranchId)
+        : uniqueStrings(input.rejectedBranchIds ?? []).filter((id) => branchIds.includes(id)));
+    if (selectedBranchId)
+        rejectedBranchIds.delete(selectedBranchId);
+    const selectorMetadata = toJsonObject(input.selector?.metadata);
+    const selector = normalizeGraphNode({
+        ...(input.selector ?? {}),
+        id: input.selector?.id ?? (input.id ? `${input.id}:selector` : graphNodeId('decision', 'race-select:' + stableHash(branchIds))),
+        kind: input.selector?.kind ?? 'decision',
+        title: input.selector?.title ?? 'Race/select',
+        metadata: {
+            ...(selectorMetadata ?? {}),
+            role: 'race-select',
+            graphChunkKind: 'race-select',
+            branchIds,
+            branchCount: branchIds.length,
+            ...(selectedBranchId ? { selectedBranchId } : {}),
+            rejectedBranchIds: Array.from(rejectedBranchIds).sort()
+        }
+    });
+    const branches = baseBranches.map((node, index) => {
+        const disposition = node.id === selectedBranchId ? 'selected' : rejectedBranchIds.has(node.id) ? 'rejected' : 'candidate';
+        return normalizeGraphNode({
+            ...node,
+            status: node.status ?? (disposition === 'selected' ? 'accepted' : disposition === 'rejected' ? 'rejected' : undefined),
+            metadata: {
+                ...(node.metadata ?? {}),
+                raceSelect: {
+                    selectorId: selector.id,
+                    branchId: node.id,
+                    branchIndex: index,
+                    branchCount: baseBranches.length,
+                    disposition,
+                    selected: disposition === 'selected',
+                    rejected: disposition === 'rejected'
+                }
+            }
+        }, node.generatedAt);
+    });
+    return createSwarmRunGraphChunk({
+        id: input.id,
+        nodes: [selector, ...branches],
+        edges: branches.map((branch, index) => {
+            const disposition = branch.id === selectedBranchId ? 'selected' : rejectedBranchIds.has(branch.id) ? 'rejected' : 'candidate';
+            return {
+                kind: disposition === 'selected' ? 'mergesInto' : disposition === 'rejected' ? 'supersedes' : 'dependsOn',
+                from: branch.id,
+                to: selector.id,
+                label: disposition,
+                metadata: {
+                    role: 'race-select-branch',
+                    selectorId: selector.id,
+                    branchId: branch.id,
+                    branchIndex: index,
+                    branchCount: branches.length,
+                    disposition,
+                    selected: disposition === 'selected',
+                    rejected: disposition === 'rejected'
+                }
+            };
+        }),
+        entryNodeIds: branchIds,
+        exitNodeIds: [selector.id],
+        metadata: input.metadata
+    });
+}
+export function createSwarmRunGraphTournament(input) {
+    const tournament = normalizeGraphNode({ id: input.id ? `${input.id}:tournament` : undefined, kind: 'decision', title: 'Tournament', metadata: input.metadata });
+    const candidates = input.candidates.map((node) => normalizeGraphNode({ ...node, kind: node.kind ?? 'candidate' }));
+    const rejected = new Set(input.rejectedCandidates ?? []);
+    const edges = candidates.map((candidate) => ({
+        kind: candidate.id === input.winner ? 'mergesInto' : rejected.has(candidate.id) ? 'supersedes' : 'dependsOn',
+        from: candidate.id,
+        to: tournament.id,
+        label: candidate.id === input.winner ? 'winner' : rejected.has(candidate.id) ? 'rejected' : 'candidate'
+    }));
+    return createSwarmRunGraphChunk({
+        id: input.id,
+        nodes: [tournament, ...candidates],
+        edges,
+        entryNodeIds: candidates.map((candidate) => candidate.id),
+        exitNodeIds: [tournament.id],
+        metadata: input.metadata
+    });
+}
+export function createSwarmRunGraphRetryLoop(input) {
+    const action = normalizeGraphNode(input.action);
+    const gate = normalizeGraphNode({ ...input.gate, kind: input.gate.kind ?? 'gate' });
+    const retry = normalizeGraphNode(input.retry);
+    const optional = [input.success, input.failure].filter((node) => Boolean(node)).map((node) => normalizeGraphNode(node));
+    return createSwarmRunGraphChunk({
+        id: input.id,
+        nodes: [action, gate, retry, ...optional],
+        edges: [
+            { kind: 'verifies', from: action.id, to: gate.id },
+            { kind: 'blocks', from: gate.id, to: retry.id, label: 'retry' },
+            { kind: 'dependsOn', from: retry.id, to: action.id, label: 'loop' },
+            ...optional.map((node) => ({ kind: node.status === 'failed' ? 'blocks' : 'mergesInto', from: gate.id, to: node.id }))
+        ],
+        entryNodeIds: [action.id],
+        exitNodeIds: optional.length > 0 ? optional.map((node) => node.id) : [gate.id],
+        metadata: input.metadata
+    });
+}
+export function createSwarmRunGraphRsiLoop(input) {
+    const observe = normalizeGraphNode({ ...input.observe, kind: input.observe.kind ?? 'rsi' });
+    const improve = normalizeGraphNode({ ...input.improve, kind: input.improve.kind ?? 'rsi' });
+    const apply = input.apply ? normalizeGraphNode(input.apply) : undefined;
+    return createSwarmRunGraphChunk({
+        id: input.id,
+        nodes: apply ? [observe, improve, apply] : [observe, improve],
+        edges: [
+            { kind: 'produces', from: observe.id, to: improve.id, label: 'feedback' },
+            ...(apply ? [{ kind: 'mergesInto', from: improve.id, to: apply.id, label: 'applies' }] : [])
+        ],
+        entryNodeIds: [observe.id],
+        exitNodeIds: [apply?.id ?? improve.id],
+        metadata: input.metadata
+    });
+}
+export function createSwarmRunGraphSynthesisChunk(input = {}) {
+    const source = input.source ? normalizeGraphNode(input.source) : undefined;
+    const panel = normalizeGraphNode({
+        ...input.panel,
+        id: input.panel?.id ?? (input.id ? `${input.id}:panel` : undefined),
+        kind: input.panel?.kind ?? 'decision',
+        title: input.panel?.title ?? 'Synthesis panel'
+    });
+    const candidates = (input.candidates ?? []).map((candidate) => normalizeGraphNode({
+        ...candidate,
+        kind: candidate.kind ?? 'candidate'
+    }));
+    const rejectedCandidateIds = new Set(input.rejectedCandidateIds ?? candidates
+        .filter((candidate) => candidate.status === 'rejected' || candidate.status === 'failed' || candidate.status === 'superseded')
+        .map((candidate) => candidate.id));
+    const selectedCandidateId = input.selectedCandidateId ?? candidates.find((candidate) => !rejectedCandidateIds.has(candidate.id))?.id;
+    const selectedCandidate = selectedCandidateId ? candidates.find((candidate) => candidate.id === selectedCandidateId) : undefined;
+    const decision = input.decision ? normalizeGraphNode({
+        ...input.decision,
+        id: input.decision.id ?? (input.id ? `${input.id}:decision` : undefined),
+        kind: input.decision.kind ?? 'decision',
+        title: input.decision.title ?? 'Coordinator synthesis decision'
+    }) : undefined;
+    const output = input.output ? normalizeGraphNode({
+        ...input.output,
+        kind: input.output.kind ?? 'candidate'
+    }) : undefined;
+    const edges = [];
+    if (source) {
+        edges.push({ kind: 'produces', from: source.id, to: panel.id, label: 'synthesis-request' });
+    }
+    for (const candidate of candidates) {
+        edges.push({ kind: 'produces', from: panel.id, to: candidate.id, label: 'candidate' });
+    }
+    if (decision && selectedCandidate) {
+        edges.push({ kind: 'mergesInto', from: selectedCandidate.id, to: decision.id, label: 'selected' });
+    }
+    for (const candidate of candidates) {
+        if (!rejectedCandidateIds.has(candidate.id))
+            continue;
+        edges.push(selectedCandidate && selectedCandidate.id !== candidate.id
+            ? { kind: 'supersedes', from: selectedCandidate.id, to: candidate.id, label: 'rejected' }
+            : { kind: 'supersedes', from: candidate.id, to: decision?.id ?? panel.id, label: 'rejected' });
+    }
+    if (decision && output) {
+        edges.push({
+            kind: isBlockingGraphStatus(decision.status) ? 'blocks' : 'produces',
+            from: decision.id,
+            to: output.id,
+            label: isBlockingGraphStatus(decision.status) ? 'blocked-output' : 'synthesized-output'
+        });
+    }
+    else if (selectedCandidate && output) {
+        edges.push({ kind: 'mergesInto', from: selectedCandidate.id, to: output.id, label: 'synthesized-output' });
+    }
+    const nodes = [source, panel, ...candidates, decision, output].filter((node) => Boolean(node));
+    return createSwarmRunGraphChunk({
+        id: input.id,
+        nodes,
+        edges,
+        entryNodeIds: [source?.id ?? panel.id],
+        exitNodeIds: [output?.id ?? decision?.id ?? selectedCandidate?.id ?? panel.id],
+        metadata: input.metadata
+    });
+}
+export function createSwarmRunGraphVerificationGateChunk(input) {
+    const subject = normalizeGraphNode(input.subject);
+    const gate = normalizeGraphNode({
+        ...input.gate,
+        kind: input.gate.kind ?? 'gate',
+        title: input.gate.title ?? 'Verification gate'
+    });
+    const evidence = (input.evidence ?? []).map((node) => normalizeGraphNode({
+        ...node,
+        kind: node.kind ?? 'evidence'
+    }));
+    const pass = input.pass ? normalizeGraphNode(input.pass) : undefined;
+    const block = input.block ? normalizeGraphNode(input.block) : undefined;
+    const passing = isPassingGraphStatus(gate.status);
+    const blocking = isBlockingGraphStatus(gate.status);
+    const edges = [
+        { kind: 'verifies', from: gate.id, to: subject.id, label: 'gate' },
+        ...evidence.map((node) => ({ kind: 'produces', from: gate.id, to: node.id, label: 'evidence' })),
+        ...evidence.map((node) => ({ kind: 'verifies', from: node.id, to: gate.id, label: 'evidence-verifies-gate' }))
+    ];
+    if (passing && pass) {
+        edges.push({ kind: 'mergesInto', from: gate.id, to: pass.id, label: 'passed' });
+    }
+    if (blocking) {
+        edges.push({ kind: 'blocks', from: gate.id, to: block?.id ?? subject.id, label: gate.status === 'failed' ? 'failed' : 'blocked' });
+    }
+    return createSwarmRunGraphChunk({
+        id: input.id,
+        nodes: [subject, gate, ...evidence, pass, block].filter((node) => Boolean(node)),
+        edges,
+        entryNodeIds: [subject.id],
+        exitNodeIds: [passing && pass ? pass.id : blocking && block ? block.id : gate.id],
+        metadata: input.metadata
+    });
+}
+export function createSwarmRunGraphMergeGateChunk(input) {
+    const candidate = normalizeGraphNode({
+        ...input.candidate,
+        kind: input.candidate.kind ?? 'candidate'
+    });
+    const target = normalizeGraphNode(input.target);
+    const gate = input.gate ? normalizeGraphNode({
+        ...input.gate,
+        kind: input.gate.kind ?? 'gate',
+        title: input.gate.title ?? 'Merge gate'
+    }) : undefined;
+    const decision = input.decision ? normalizeGraphNode({
+        ...input.decision,
+        kind: input.decision.kind ?? 'decision',
+        title: input.decision.title ?? 'Coordinator merge decision'
+    }) : undefined;
+    const blockers = (input.blockers ?? []).map((node) => normalizeGraphNode({
+        ...node,
+        kind: node.kind ?? 'gate'
+    }));
+    const superseded = (input.superseded ?? []).map((node) => normalizeGraphNode({
+        ...node,
+        kind: node.kind ?? 'candidate'
+    }));
+    const status = input.status ?? decision?.status ?? gate?.status ?? candidate.status;
+    const passing = isPassingGraphStatus(status);
+    const blocking = isBlockingGraphStatus(status);
+    const edges = [];
+    if (gate) {
+        edges.push({ kind: 'verifies', from: gate.id, to: candidate.id, label: 'merge-gate' });
+    }
+    if (gate && decision) {
+        edges.push({ kind: blocking ? 'blocks' : 'produces', from: gate.id, to: decision.id, label: 'gate-decision' });
+    }
+    if (decision) {
+        edges.push({ kind: 'verifies', from: decision.id, to: candidate.id, label: 'coordinator-decision' });
+    }
+    for (const blocker of blockers) {
+        edges.push({ kind: 'blocks', from: blocker.id, to: candidate.id, label: 'merge-blocker' });
+    }
+    for (const node of superseded) {
+        edges.push({ kind: 'supersedes', from: candidate.id, to: node.id, label: 'superseded' });
+    }
+    if (passing) {
+        edges.push({ kind: 'mergesInto', from: candidate.id, to: target.id, label: 'accepted' });
+    }
+    else if (blocking) {
+        edges.push({ kind: 'blocks', from: decision?.id ?? gate?.id ?? candidate.id, to: target.id, label: status === 'failed' ? 'failed' : 'blocked' });
+    }
+    return createSwarmRunGraphChunk({
+        id: input.id,
+        nodes: [candidate, target, gate, decision, ...blockers, ...superseded].filter((node) => Boolean(node)),
+        edges,
+        entryNodeIds: [candidate.id],
+        exitNodeIds: [passing ? target.id : blocking ? decision?.id ?? gate?.id ?? candidate.id : target.id],
+        metadata: input.metadata
+    });
+}
 export const FRONTIER_SWARM_TASK_MODEL_PROFILES = [
     {
         workKind: 'agent-task',
@@ -748,7 +1839,498 @@ export function createSwarmRun(input) {
         summary: summarizeRun(input.plan.jobs, results),
         ...(toJsonObject(input.metadata) ? { metadata: toJsonObject(input.metadata) } : {})
     };
-    return run;
+    return run;
+}
+export function createRunEventsFromSwarmPlan(plan, options = {}) {
+    const actorId = options.actorId ?? 'frontier-swarm';
+    const runId = options.runId ?? plan.runId;
+    const time = swarmRunEventTime(options, plan.createdAt);
+    let actorSeq = options.startActorSeq ?? 1;
+    const events = [];
+    const created = createRunEvent({
+        runId,
+        actorId,
+        actorSeq: actorSeq++,
+        parents: [...(options.parents ?? [])],
+        time,
+        type: 'run.created',
+        payload: {
+            goal: plan.metadata?.objective ?? plan.metadata?.goal ?? `Frontier swarm ${plan.id}`,
+            metadata: pruneUndefinedJsonObject({
+                source: 'frontier-swarm.plan',
+                planId: plan.id,
+                manifestId: plan.manifestId,
+                summary: plan.summary,
+                filters: plan.filters,
+                limits: plan.limits,
+                metadata: plan.metadata,
+                adapterMetadata: toJsonObject(options.metadata)
+            })
+        }
+    });
+    events.push(created);
+    const laneIds = uniqueStrings(plan.jobs.map((job) => job.lane));
+    const laneEventByLane = new Map();
+    for (const lane of laneIds) {
+        const laneJobs = plan.jobs.filter((job) => job.lane === lane);
+        const laneEvent = createRunNodeEvent(runId, actorId, actorSeq++, defineRunLane({
+            id: swarmRunLaneNodeId(lane),
+            title: lane,
+            packageId: inferSwarmLanePackageId(laneJobs),
+            allowedWrites: uniqueStrings(laneJobs.flatMap((job) => job.allowedWrites)),
+            requiredChecks: uniqueStrings(laneJobs.flatMap((job) => job.verification.map(formatSwarmCommandLine))),
+            maxConcurrency: plan.limits.maxLaneConcurrency[lane],
+            concurrencyKey: lane,
+            semanticRegions: uniqueStrings(laneJobs.flatMap((job) => [...job.ownedRegions, ...job.changedRegions])),
+            status: 'ready',
+            createdAt: time,
+            updatedAt: time,
+            metadata: pruneUndefinedJsonObject({
+                source: 'frontier-swarm.plan.lane',
+                jobIds: laneJobs.map((job) => job.id),
+                taskIds: uniqueStrings(laneJobs.map((job) => job.taskId))
+            })
+        }), {
+            parents: [created.id],
+            time
+        });
+        events.push(laneEvent);
+        laneEventByLane.set(lane, laneEvent);
+    }
+    const taskById = new Map();
+    for (const job of plan.jobs)
+        if (!taskById.has(job.taskId))
+            taskById.set(job.taskId, job);
+    for (const job of taskById.values()) {
+        const task = job.task;
+        const taskEvent = createRunNodeEvent(runId, actorId, actorSeq++, defineRunTask({
+            id: swarmRunTaskNodeId(job.taskId),
+            title: task.title || job.title,
+            laneId: swarmRunLaneNodeId(job.lane),
+            status: swarmStatusToRunStatus(job.status),
+            targetRefs: uniqueStrings([...(task.targetRefs ?? []), ...job.allowedWrites]),
+            sourceRefs: task.sourceRefs,
+            allowedWrites: job.allowedWrites,
+            semanticRegions: uniqueStrings([...job.ownedRegions, ...job.changedRegions]),
+            acceptance: job.acceptance,
+            verification: job.verification.map((command) => ({
+                id: command.name,
+                command: command.command,
+                args: command.args,
+                cwd: command.cwd,
+                required: command.required,
+                metadata: command.metadata
+            })),
+            priority: job.priority,
+            concurrencyKey: job.concurrencyKey,
+            createdAt: time,
+            updatedAt: time,
+            metadata: pruneUndefinedJsonObject({
+                source: 'frontier-swarm.plan.task',
+                jobIds: plan.jobs.filter((entry) => entry.taskId === job.taskId).map((entry) => entry.id),
+                workKind: task.workKind,
+                layer: job.layer,
+                compute: job.compute.id,
+                tags: job.tags,
+                task: task
+            })
+        }), {
+            parents: [laneEventByLane.get(job.lane)?.id ?? created.id],
+            time
+        });
+        events.push(taskEvent);
+    }
+    return events;
+}
+export function createRunEventsFromSwarmLease(lease, options = {}) {
+    const actorId = options.actorId ?? lease.workerId ?? 'frontier-swarm';
+    const runId = options.runId ?? options.job?.metadata?.runId ?? 'frontier-swarm';
+    const eventType = options.eventType ?? (lease.status === 'released' ? 'lease.released' : 'lease.granted');
+    const time = swarmRunEventTime(options, eventType === 'lease.released' ? options.now : lease.leasedAt);
+    const leaseNode = {
+        kind: 'lease',
+        id: swarmRunLeaseNodeId(lease.id),
+        title: `Lease ${lease.jobId}`,
+        scopeId: options.job ? swarmRunTaskNodeId(options.job.taskId) : swarmRunTaskNodeId(lease.jobId),
+        leaseKey: options.job?.concurrencyKey ?? lease.jobId,
+        holderId: lease.workerId,
+        status: eventType === 'lease.released' ? 'released' : 'granted',
+        requestedAt: new Date(lease.leasedAt).toISOString(),
+        grantedAt: new Date(lease.leasedAt).toISOString(),
+        releasedAt: eventType === 'lease.released' ? time : undefined,
+        metadata: pruneUndefinedJsonObject({
+            source: 'frontier-swarm.lease',
+            jobId: lease.jobId,
+            token: lease.token,
+            fencingToken: lease.fencingToken,
+            expiresAt: lease.expiresAt,
+            status: lease.status
+        })
+    };
+    return [createRunEvent({
+            runId,
+            actorId,
+            actorSeq: options.startActorSeq ?? 1,
+            parents: [...(options.parents ?? [])],
+            time,
+            type: eventType,
+            payload: pruneUndefinedJsonObject({
+                subjectId: options.job ? swarmRunTaskNodeId(options.job.taskId) : undefined,
+                lease: leaseNode
+            })
+        })];
+}
+export function createRunEventsFromSwarmResult(resultInput, options = {}) {
+    const result = isSwarmJobResult(resultInput) ? cloneJsonValue(resultInput) : normalizeResult(resultInput);
+    const job = options.job;
+    const runId = options.runId ?? 'frontier-swarm';
+    const actorId = options.actorId ?? 'frontier-swarm-worker';
+    const time = swarmRunEventTime(options, result.finishedAt ?? result.startedAt);
+    let actorSeq = options.startActorSeq ?? 1;
+    const parents = [...(options.parents ?? [])];
+    const events = [];
+    const attemptId = swarmRunAttemptNodeId(result.jobId);
+    const taskId = swarmRunTaskNodeId(job?.taskId ?? result.jobId);
+    const attemptEvent = createRunNodeEvent(runId, actorId, actorSeq++, defineRunAttempt({
+        id: attemptId,
+        title: job?.title ?? result.jobId,
+        taskId,
+        actorId,
+        runnerId: job?.compute.kind ?? job?.compute.id,
+        workspaceId: job?.worktreePath,
+        status: swarmResultStatusToAttemptStatus(result.status),
+        startedAt: result.startedAt ? new Date(result.startedAt).toISOString() : undefined,
+        endedAt: result.finishedAt ? new Date(result.finishedAt).toISOString() : undefined,
+        model: job?.compute.model,
+        reason: result.error,
+        metadata: pruneUndefinedJsonObject({
+            source: 'frontier-swarm.result',
+            jobId: result.jobId,
+            mergeReadiness: result.mergeReadiness,
+            mergeDisposition: result.mergeDisposition,
+            riskLevel: result.riskLevel,
+            exitCode: result.exitCode,
+            signal: result.signal,
+            queueItemIds: result.queueItemIds,
+            semanticImport: result.semanticImport,
+            metadata: result.metadata
+        })
+    }), { parents, time });
+    events.push(attemptEvent);
+    let latestParents = [attemptEvent.id];
+    if (result.patchPath || result.changedPaths.length) {
+        const patchId = swarmRunPatchNodeId(result.jobId);
+        const patchEvent = createRunNodeEvent(runId, actorId, actorSeq++, defineRunPatch({
+            id: patchId,
+            title: `Patch ${result.jobId}`,
+            changedPaths: result.changedPaths,
+            artifactId: result.patchPath ? swarmRunArtifactNodeId(result.patchPath) : undefined,
+            summary: result.lastMessage,
+            risk: swarmRiskToRunRisk(result.riskLevel),
+            metadata: pruneUndefinedJsonObject({
+                source: 'frontier-swarm.result.patch',
+                patchPath: result.patchPath,
+                changedRegions: result.changedRegions,
+                ownershipViolations: result.ownershipViolations
+            })
+        }), { parents: latestParents, time });
+        events.push(patchEvent);
+        events.push(createRunEdgeEvent(runId, actorId, actorSeq++, linkRunNodes(attemptId, patchId, 'produces-patch', { createdAt: time }), {
+            parents: [patchEvent.id],
+            time
+        }));
+        if (result.patchPath) {
+            events.push(createRunEvent({
+                runId,
+                actorId,
+                actorSeq: actorSeq++,
+                parents: [patchEvent.id],
+                time,
+                type: 'artifact.attached',
+                payload: {
+                    subjectId: patchId,
+                    artifact: toJsonValue(defineRunArtifact({
+                        id: swarmRunArtifactNodeId(result.patchPath),
+                        title: result.patchPath,
+                        artifactType: 'patch',
+                        path: result.patchPath,
+                        summary: `Patch artifact for ${result.jobId}`,
+                        metadata: { source: 'frontier-swarm.result.patch-artifact', jobId: result.jobId }
+                    }))
+                }
+            }));
+        }
+        latestParents = [patchEvent.id];
+    }
+    for (const evidencePath of result.evidencePaths) {
+        const artifactId = swarmRunArtifactNodeId(evidencePath);
+        const evidenceId = swarmRunEvidenceNodeId(result.jobId, evidencePath);
+        const artifactEvent = createRunEvent({
+            runId,
+            actorId,
+            actorSeq: actorSeq++,
+            parents: latestParents,
+            time,
+            type: 'artifact.attached',
+            payload: {
+                subjectId: attemptId,
+                artifact: toJsonValue(defineRunArtifact({
+                    id: artifactId,
+                    title: evidencePath,
+                    artifactType: inferSwarmArtifactType(evidencePath),
+                    path: evidencePath,
+                    summary: `Evidence artifact for ${result.jobId}`,
+                    metadata: { source: 'frontier-swarm.result.evidence-artifact', jobId: result.jobId }
+                }))
+            }
+        });
+        events.push(artifactEvent);
+        const evidenceEvent = createRunNodeEvent(runId, actorId, actorSeq++, defineRunEvidence({
+            id: evidenceId,
+            title: evidencePath,
+            evidenceType: inferSwarmArtifactType(evidencePath),
+            result: result.status === 'completed' || result.status === 'verified' ? 'pass' : result.status === 'failed' ? 'fail' : 'unknown',
+            artifactIds: [artifactId],
+            summary: `Evidence from ${result.jobId}`,
+            metadata: { source: 'frontier-swarm.result.evidence', jobId: result.jobId }
+        }), { parents: [artifactEvent.id], time });
+        events.push(evidenceEvent);
+        events.push(createRunEdgeEvent(runId, actorId, actorSeq++, linkRunNodes(attemptId, evidenceId, 'produces-evidence', { createdAt: time }), {
+            parents: [evidenceEvent.id],
+            time
+        }));
+    }
+    for (let index = 0; index < result.verification.length; index += 1) {
+        const verification = result.verification[index];
+        const verificationId = swarmRunVerificationNodeId(result.jobId, index, verification.name);
+        const verificationEvent = createRunNodeEvent(runId, actorId, actorSeq++, defineRunVerification({
+            id: verificationId,
+            title: verification.name,
+            status: verification.status === 0 ? 'passed' : verification.required === false && verification.status !== 0 ? 'skipped' : 'failed',
+            command: verification.command[0],
+            args: verification.command.slice(1),
+            cwd: verification.cwd,
+            exitCode: verification.status,
+            artifactIds: [],
+            required: verification.required,
+            summary: verification.commandLine,
+            metadata: pruneUndefinedJsonObject({
+                source: 'frontier-swarm.result.verification',
+                jobId: result.jobId,
+                durationMs: verification.durationMs,
+                stdoutTail: verification.stdoutTail,
+                stderrTail: verification.stderrTail,
+                category: verification.category,
+                metadata: verification.metadata
+            })
+        }), { parents: latestParents, time });
+        events.push(verificationEvent);
+        events.push(createRunEdgeEvent(runId, actorId, actorSeq++, linkRunNodes(attemptId, verificationId, 'verified-by', { createdAt: time }), {
+            parents: [verificationEvent.id],
+            time
+        }));
+    }
+    return events;
+}
+export function createRunEventsFromMergeBundle(bundle, options = {}) {
+    const runId = options.runId ?? bundle.runId ?? 'frontier-swarm';
+    const actorId = options.actorId ?? 'frontier-swarm-collector';
+    const time = swarmRunEventTime(options, bundle.generatedAt);
+    let actorSeq = options.startActorSeq ?? 1;
+    const parents = [...(options.parents ?? [])];
+    const events = [];
+    const patchId = swarmRunPatchNodeId(bundle.jobId);
+    const patchEvent = createRunNodeEvent(runId, actorId, actorSeq++, defineRunPatch({
+        id: patchId,
+        title: bundle.title ?? `Merge bundle ${bundle.jobId}`,
+        changedPaths: bundle.changedPaths,
+        artifactId: bundle.patchPath ? swarmRunArtifactNodeId(bundle.patchPath) : undefined,
+        summary: bundle.reasons.join('; '),
+        risk: swarmRiskToRunRisk(bundle.riskLevel),
+        metadata: pruneUndefinedJsonObject({
+            source: 'frontier-swarm.merge-bundle',
+            bundleId: bundle.id,
+            jobId: bundle.jobId,
+            taskId: bundle.taskId,
+            lane: bundle.lane,
+            mergeReadiness: bundle.mergeReadiness,
+            disposition: bundle.disposition,
+            autoMergeable: bundle.autoMergeable,
+            staleAgainstHead: bundle.staleAgainstHead,
+            changedRegions: bundle.changedRegions,
+            ownedFilesTouched: bundle.ownedFilesTouched,
+            ownershipViolations: bundle.ownershipViolations,
+            patchHash: bundle.patchHash,
+            branchName: bundle.branchName,
+            commit: bundle.commit,
+            semanticImport: bundle.semanticImport
+        })
+    }), { parents, time });
+    events.push(patchEvent);
+    if (bundle.patchPath) {
+        events.push(createRunEvent({
+            runId,
+            actorId,
+            actorSeq: actorSeq++,
+            parents: [patchEvent.id],
+            time,
+            type: 'artifact.attached',
+            payload: {
+                subjectId: patchId,
+                artifact: toJsonValue(defineRunArtifact({
+                    id: swarmRunArtifactNodeId(bundle.patchPath),
+                    title: bundle.patchPath,
+                    artifactType: 'patch',
+                    path: bundle.patchPath,
+                    hash: bundle.patchHash,
+                    summary: `Merge patch for ${bundle.jobId}`,
+                    metadata: { source: 'frontier-swarm.merge-bundle.patch', bundleId: bundle.id }
+                }))
+            }
+        }));
+    }
+    for (const evidencePath of bundle.evidencePaths) {
+        events.push(createRunEvent({
+            runId,
+            actorId,
+            actorSeq: actorSeq++,
+            parents: [patchEvent.id],
+            time,
+            type: 'artifact.attached',
+            payload: {
+                subjectId: patchId,
+                artifact: toJsonValue(defineRunArtifact({
+                    id: swarmRunArtifactNodeId(evidencePath),
+                    title: evidencePath,
+                    artifactType: inferSwarmArtifactType(evidencePath),
+                    path: evidencePath,
+                    summary: `Merge evidence for ${bundle.jobId}`,
+                    metadata: { source: 'frontier-swarm.merge-bundle.evidence', bundleId: bundle.id }
+                }))
+            }
+        }));
+    }
+    const decisionKind = swarmDispositionToRunDecision(bundle.disposition, bundle.mergeReadiness);
+    const decisionEvent = createRunEvent({
+        runId,
+        actorId,
+        actorSeq: actorSeq++,
+        parents: [patchEvent.id],
+        time,
+        type: 'decision.recorded',
+        payload: {
+            decision: toJsonValue(defineRunDecision({
+                id: swarmRunDecisionNodeId(bundle.id || bundle.jobId),
+                title: `Merge decision ${bundle.jobId}`,
+                decision: decisionKind,
+                subjectIds: uniqueStrings([patchId, bundle.taskId ? swarmRunTaskNodeId(bundle.taskId) : undefined]),
+                actorId,
+                reason: bundle.reasons.join('; ') || bundle.disposition,
+                requiredActions: bundle.disposition === 'needs-port' ? ['human-port'] : bundle.staleAgainstHead ? ['rerun-against-head'] : [],
+                metadata: pruneUndefinedJsonObject({
+                    source: 'frontier-swarm.merge-bundle.decision',
+                    bundleId: bundle.id,
+                    disposition: bundle.disposition,
+                    mergeReadiness: bundle.mergeReadiness,
+                    riskLevel: bundle.riskLevel,
+                    autoMergeable: bundle.autoMergeable
+                })
+            }))
+        }
+    });
+    events.push(decisionEvent);
+    return events;
+}
+export function createRunEventsFromCoordinatorDecision(decision, options = {}) {
+    const normalized = createSwarmQueueOutcomeDecision(decision);
+    const runId = options.runId ?? 'frontier-swarm';
+    const actorId = options.actorId ?? 'frontier-swarm-coordinator';
+    const time = swarmRunEventTime(options, normalized.generatedAt);
+    const subjectIds = uniqueStrings([
+        normalized.jobId ? swarmRunAttemptNodeId(normalized.jobId) : undefined,
+        normalized.taskId ? swarmRunTaskNodeId(normalized.taskId) : undefined,
+        normalized.subjectId
+    ]);
+    return [createRunEvent({
+            runId,
+            actorId,
+            actorSeq: options.startActorSeq ?? 1,
+            parents: [...(options.parents ?? [])],
+            time,
+            type: 'decision.recorded',
+            payload: {
+                decision: toJsonValue(defineRunDecision({
+                    id: swarmRunDecisionNodeId(normalized.id),
+                    title: `Coordinator decision ${normalized.subjectId}`,
+                    decision: swarmQueueOutcomeToRunDecision(normalized),
+                    subjectIds,
+                    actorId,
+                    reason: normalized.reasons.join('; ') || normalized.outcome,
+                    requiredActions: swarmQueueOutcomeRequiredActions(normalized),
+                    metadata: pruneUndefinedJsonObject({
+                        source: 'frontier-swarm.queue-outcome-decision',
+                        decision: normalized.decision,
+                        action: normalized.action,
+                        assignedAction: normalized.assignedAction,
+                        category: normalized.category,
+                        outcome: normalized.outcome,
+                        terminal: normalized.terminal,
+                        queueItemIds: normalized.queueItemIds,
+                        queueId: normalized.queueId,
+                        lane: normalized.lane,
+                        disposition: normalized.disposition,
+                        mergeReadiness: normalized.mergeReadiness,
+                        status: normalized.status,
+                        conflictingJobIds: normalized.conflictingJobIds,
+                        metadata: normalized.metadata
+                    })
+                }))
+            }
+        })];
+}
+export function createRunProjectionFromSwarmRunEvents(events, options = {}) {
+    return replayRunEvents(events, {
+        id: options.runId,
+        goal: options.goal,
+        metadata: toJsonObject(options.metadata)
+    });
+}
+export function createRunDashboardFromSwarmRun(input, options = {}) {
+    const events = isFrontierRunEventList(input) ? input : createRunEventsFromSwarmRun(input, options);
+    return createRunDashboardSnapshot(createRunProjectionFromSwarmRunEvents(events, options));
+}
+export function createRunEventsFromSwarmRun(run, options = {}) {
+    const runId = options.runId ?? run.id;
+    const actorId = options.actorId ?? 'frontier-swarm';
+    const created = createRunEvent({
+        runId,
+        actorId,
+        actorSeq: options.startActorSeq ?? 1,
+        parents: [...(options.parents ?? [])],
+        time: swarmRunEventTime(options, run.startedAt),
+        type: 'run.created',
+        payload: {
+            goal: run.metadata?.objective ?? run.metadata?.goal ?? `Frontier swarm ${run.id}`,
+            metadata: pruneUndefinedJsonObject({
+                source: 'frontier-swarm.run',
+                planId: run.planId,
+                manifestId: run.manifestId,
+                status: run.status,
+                summary: run.summary,
+                metadata: run.metadata
+            })
+        }
+    });
+    return [
+        created,
+        ...run.results.flatMap((result, index) => createRunEventsFromSwarmResult(result, {
+            runId,
+            actorId: 'frontier-swarm-worker',
+            startActorSeq: 1000 + index * 100,
+            parents: [created.id],
+            job: run.jobs.find((job) => job.id === result.jobId)
+        }))
+    ];
 }
 export function recordSwarmEvent(runInput, eventInput) {
     const run = cloneJsonValue(runInput);
@@ -1030,6 +2612,14 @@ const SEMANTIC_IMPORT_CONFLICT_HINT_KEYS = new Set([
     'symbols',
     'touchedSymbols'
 ]);
+const SEMANTIC_IMPORT_PUBLIC_CONTRACT_HINT_KEYS = new Set([
+    'apiContract',
+    'apiContracts',
+    'publicContract',
+    'publicContractId',
+    'publicContractIds',
+    'publicContracts'
+]);
 function semanticImportExportMetadata(value, key, file) {
     const explicitKind = semanticImportStringValue(value.kind);
     const declarationKind = semanticImportStringValue(value.declarationKind)
@@ -1119,9 +2709,28 @@ function semanticImportStringValue(value) {
 function semanticMergeConflictKeys(semanticImport) {
     const records = semanticImportRecords(semanticImport);
     const sources = records.length > 0 ? records : [semanticImport];
-    return uniqueStrings(sources.flatMap((source) => semanticImportConflictHintStringsForValue('mergeCandidate' in source && source.mergeCandidate !== undefined
+    return uniqueStrings(sources.flatMap((source) => semanticImportConflictKeyStringsForValue('mergeCandidate' in source && source.mergeCandidate !== undefined
         ? source.mergeCandidate
-        : source).map((symbol) => `symbol:${symbol}`)));
+        : source)));
+}
+function semanticImportConflictKeyStringsForValue(value, key, depth = 0) {
+    if (value === undefined || value === null)
+        return [];
+    if (typeof value === 'string') {
+        const normalized = value.trim();
+        if (!normalized)
+            return [];
+        if (key && SEMANTIC_IMPORT_PUBLIC_CONTRACT_HINT_KEYS.has(key))
+            return [`public-contract:${publicContractConflictValue(normalized)}`];
+        if (key && SEMANTIC_IMPORT_CONFLICT_HINT_KEYS.has(key))
+            return [`symbol:${normalized}`];
+        return [];
+    }
+    if (depth >= 4 || typeof value !== 'object')
+        return [];
+    if (Array.isArray(value))
+        return value.flatMap((item) => semanticImportConflictKeyStringsForValue(item, key, depth + 1));
+    return Object.entries(value).flatMap(([nextKey, nextValue]) => (semanticImportConflictKeyStringsForValue(nextValue, nextKey, depth + 1)));
 }
 function semanticImportConflictHintStringsForValue(value, key, depth = 0) {
     if (value === undefined || value === null)
@@ -2467,6 +4076,11 @@ export function createSwarmHierarchicalMergeQueue(input) {
     const admissionPressure = summarizeSwarmMergeAdmissionPressure(assignments);
     const orderedScopes = Array.from(scopes.values()).sort((left, right) => (mergeQueueScopeRank(left.kind) - mergeQueueScopeRank(right.kind)
         || left.id.localeCompare(right.id)));
+    const semanticLeaseScopeMap = createSwarmSemanticLeaseScopeMap(orderedScopes, {
+        rootScopeId,
+        ...semanticLeaseScopeOptionsFromMetadata(input.metadata)
+    });
+    const scopesWithSemanticLeases = orderedScopes.map((scope) => attachSemanticLeaseScopeToMergeQueueScope(scope, semanticLeaseScopeMap));
     const queueId = input.id ?? 'swarm-hierarchical-merge-queue:' + stableHash([input.index.id, input.admission?.id, orderedScopes, assignments, promotions, generatedAt]);
     const linkedAssignments = assignments.map((assignment) => {
         if (!coordinatorAgentDrainActionIsTerminal(assignment.action))
@@ -2476,19 +4090,19 @@ export function createSwarmHierarchicalMergeQueue(input) {
             terminalDecisionId: hierarchicalQueueTerminalDecisionId(queueId, assignment),
             terminalDecisionQueueItemIds: [...assignment.queueItemIds]
         };
-    });
+    }).map((assignment) => attachSemanticLeaseScopesToAssignment(assignment, semanticLeaseScopeMap));
     const leaseRecords = createHierarchicalQueueLeaseRecords({
         queueId,
         rootScopeId,
         generatedAt,
-        scopes: orderedScopes,
+        scopes: scopesWithSemanticLeases,
         assignments: linkedAssignments,
         promotions,
         localLeader: input.localLeader,
         localLeaders: input.localLeaders
     });
     const byLeaseKey = groupJobIdsByMany(linkedAssignments, (assignment) => assignment.requiredLeaseKeys ?? [assignment.leaseKey]);
-    const scopeTree = createHierarchicalQueueScopeTree(orderedScopes, rootScopeId);
+    const scopeTree = createHierarchicalQueueScopeTree(scopesWithSemanticLeases, rootScopeId);
     return {
         kind: FRONTIER_SWARM_HIERARCHICAL_MERGE_QUEUE_KIND,
         version: FRONTIER_SWARM_HIERARCHICAL_MERGE_QUEUE_VERSION,
@@ -2498,13 +4112,14 @@ export function createSwarmHierarchicalMergeQueue(input) {
         generatedAt,
         rootScopeId,
         scopeTree,
-        scopes: orderedScopes,
+        scopes: scopesWithSemanticLeases,
         leaseRecords,
         assignments: linkedAssignments,
         promotions,
         byScope,
         byLeaseKey,
         byAction,
+        semanticLeaseScopes: uniqueSemanticLeaseScopes(Array.from(semanticLeaseScopeMap.values())),
         summary: {
             scopeCount: orderedScopes.length,
             assignmentCount: linkedAssignments.length,
@@ -2534,6 +4149,7 @@ export function createSwarmCoordinatorAgentDrainWork(input) {
             title: scope.title,
             leaseScope: scope.leaseKey,
             leaseKey: scope.leaseKey,
+            ...(scope.semanticLeaseScope ? { semanticLeaseScope: scope.semanticLeaseScope } : {}),
             ...(scope.parentId ? { parentQueueId: scope.parentId } : {}),
             ...(scope.lane ? { lane: scope.lane } : {}),
             changedPaths: [...scope.changedPaths],
@@ -2563,6 +4179,9 @@ export function createSwarmCoordinatorAgentDrainWork(input) {
         const requiredLeaseKeys = assignmentRequiredLeaseKeys.length
             ? [...assignmentRequiredLeaseKeys]
             : [leaseScope];
+        const requiredSemanticLeaseScopes = requiredLeaseScopeIds
+            .map((scopeId) => scopesById.get(scopeId)?.semanticLeaseScope)
+            .filter((scope) => Boolean(scope));
         const decision = coordinatorAgentDrainDecisionForAction(assignment.action);
         const terminal = coordinatorAgentDrainActionIsTerminal(assignment.action);
         const parentQueueId = assignment.action === 'promote'
@@ -2599,6 +4218,7 @@ export function createSwarmCoordinatorAgentDrainWork(input) {
             conflictingJobIds: [...assignment.conflictingJobIds],
             requiredLeaseScopeIds,
             requiredLeaseKeys,
+            ...(requiredSemanticLeaseScopes.length ? { requiredSemanticLeaseScopes } : {}),
             ...(assignment.retrySlices?.length ? { retrySlices: cloneMergeQueueRetrySlices(assignment.retrySlices) } : {}),
             ...(assignment.semanticSliceScopeIds?.length ? { semanticSliceScopeIds: [...assignment.semanticSliceScopeIds] } : {}),
             ...(assignment.semanticSliceLeaseKeys?.length ? { semanticSliceLeaseKeys: [...assignment.semanticSliceLeaseKeys] } : {}),
@@ -2623,6 +4243,7 @@ export function createSwarmCoordinatorAgentDrainWork(input) {
         reasons: [...assignment.reasons],
         requiredLeaseScopeIds: [...(assignment.requiredLeaseScopeIds ?? [])],
         requiredLeaseKeys: [...(assignment.requiredLeaseKeys ?? [])],
+        ...(assignment.requiredSemanticLeaseScopes?.length ? { requiredSemanticLeaseScopes: assignment.requiredSemanticLeaseScopes.map(cloneSemanticLeaseScope) } : {}),
         ...(assignment.retrySlices?.length ? { retrySlices: cloneMergeQueueRetrySlices(assignment.retrySlices) } : {}),
         ...(assignment.semanticSliceScopeIds?.length ? { semanticSliceScopeIds: [...assignment.semanticSliceScopeIds] } : {}),
         ...(assignment.semanticSliceLeaseKeys?.length ? { semanticSliceLeaseKeys: [...assignment.semanticSliceLeaseKeys] } : {}),
@@ -2649,6 +4270,7 @@ export function createSwarmCoordinatorAgentDrainWork(input) {
         reasons: [...assignment.reasons],
         requiredLeaseScopeIds: [...(assignment.requiredLeaseScopeIds ?? [])],
         requiredLeaseKeys: [...(assignment.requiredLeaseKeys ?? [])],
+        ...(assignment.requiredSemanticLeaseScopes?.length ? { requiredSemanticLeaseScopes: assignment.requiredSemanticLeaseScopes.map(cloneSemanticLeaseScope) } : {}),
         ...(assignment.metadata ? { metadata: cloneJsonValue(assignment.metadata) } : {})
     }));
     const activeAssignments = assignments.filter((assignment) => !coordinatorAgentDrainAssignmentIsTerminal(assignment));
@@ -2706,6 +4328,120 @@ export function createSwarmCoordinatorAgentDrainWork(input) {
         ...(toJsonObject(input.metadata) ? { metadata: toJsonObject(input.metadata) } : {})
     };
 }
+export function createSwarmSemanticLeaseScopeForMergeQueueScope(scope, input = {}) {
+    const scopesById = new Map((input.scopes ?? []).map((entry) => [entry.id, entry]));
+    const parentKeys = [];
+    let parentId = scope.parentId;
+    const visited = new Set([scope.id]);
+    while (parentId && !visited.has(parentId)) {
+        const parent = scopesById.get(parentId);
+        if (!parent)
+            break;
+        parentKeys.push(parent.leaseKey);
+        visited.add(parentId);
+        parentId = parent.parentId;
+    }
+    const regionId = scope.changedRegions.length === 1 ? scope.changedRegions[0] : scope.id;
+    const path = scope.changedPaths.length === 1 ? scope.changedPaths[0] : undefined;
+    const metadata = mergeSwarmMetadata([
+        scope.metadata,
+        toJsonObject(input.metadata),
+        {
+            swarmQueueScopeId: scope.id,
+            swarmQueueScopeKind: scope.kind,
+            swarmLeaseKey: scope.leaseKey,
+            changedPaths: scope.changedPaths,
+            changedRegions: scope.changedRegions
+        }
+    ]);
+    return defineSemanticLeaseScope({
+        kind: semanticLeaseScopeKindForMergeQueueScope(scope),
+        key: scope.leaseKey,
+        repository: input.repository,
+        packageId: input.packageId,
+        lane: scope.lane,
+        path,
+        regionId,
+        name: semanticLeaseScopeNameForMergeQueueScope(scope),
+        parentKeys,
+        metadata
+    });
+}
+export function createSwarmSemanticLeaseScopesForMergeQueue(queue, input = {}) {
+    const existing = queue.scopes
+        .map((scope) => scope.semanticLeaseScope)
+        .filter((scope) => Boolean(scope));
+    if (existing.length)
+        return uniqueSemanticLeaseScopes(existing);
+    return uniqueSemanticLeaseScopes(queue.scopes.map((scope) => (createSwarmSemanticLeaseScopeForMergeQueueScope(scope, {
+        ...input,
+        rootScopeId: input.rootScopeId ?? queue.rootScopeId,
+        scopes: queue.scopes
+    }))));
+}
+export function createSwarmSemanticLeaseStateForMergeQueue(queue, input = {}) {
+    const semanticLeaseScopes = createSwarmSemanticLeaseScopesForMergeQueue(queue, input);
+    return createSemanticLeaseState({
+        id: input.id ?? `frontier-swarm-merge-queue:${queue.id}`,
+        defaultTtlMs: input.defaultTtlMs,
+        metadata: mergeSwarmMetadata([
+            toJsonObject(input.metadata),
+            {
+                swarmQueueId: queue.id,
+                swarmMergeIndexId: queue.mergeIndexId,
+                rootScopeId: queue.rootScopeId,
+                semanticLeaseScopeCount: semanticLeaseScopes.length,
+                generatedAt: input.now ?? queue.generatedAt
+            }
+        ])
+    });
+}
+export function acquireSwarmCoordinatorSemanticLease(input) {
+    const scopes = semanticLeaseScopesForCoordinatorAssignment(input.queue, input.assignment, input);
+    const requiredLeaseScopeIds = coordinatorAssignmentRequiredLeaseScopeIds(input.assignment);
+    const requiredLeaseKeys = coordinatorAssignmentRequiredLeaseKeys(input.assignment, scopes);
+    const state = input.state ?? createSwarmSemanticLeaseStateForMergeQueue(input.queue, input);
+    const acquireInput = {
+        ownerId: input.ownerId,
+        holderId: input.holderId,
+        now: input.now,
+        ttlMs: input.ttlMs,
+        purpose: input.purpose ?? `frontier swarm coordinator apply: ${input.assignment.jobId}`,
+        reason: input.reason,
+        scopes,
+        metadata: mergeSwarmMetadata([
+            toJsonObject(input.metadata),
+            {
+                swarmQueueId: input.queue.id,
+                swarmJobId: input.assignment.jobId,
+                swarmTaskId: input.assignment.taskId,
+                requiredLeaseScopeIds,
+                requiredLeaseKeys
+            }
+        ])
+    };
+    const mutation = acquireSemanticLease(state, acquireInput);
+    return {
+        state: mutation.state,
+        mutation,
+        scopes,
+        requiredLeaseScopeIds,
+        requiredLeaseKeys,
+        ...(mutation.lease ? { lease: mutation.lease } : {})
+    };
+}
+export function validateSwarmCoordinatorSemanticLeaseFence(input) {
+    const requiredScopes = input.requiredSemanticLeaseScopes?.length
+        ? input.requiredSemanticLeaseScopes.map(cloneSemanticLeaseScope)
+        : (input.assignment.requiredSemanticLeaseScopes ?? []).map(cloneSemanticLeaseScope);
+    return validateSemanticLeaseFence(input.state, {
+        leaseId: input.leaseId ?? input.lease?.id ?? '',
+        token: input.token,
+        fencingToken: input.fencingToken,
+        now: input.now,
+        scopes: requiredScopes.length ? requiredScopes : undefined
+    });
+}
 export function summarizeSwarmCoordinatorAgentDrainWork(work) {
     const activeAssignments = work.assignments.filter((assignment) => !coordinatorAgentDrainAssignmentIsTerminal(assignment));
     const terminalAssignments = work.assignments.filter((assignment) => coordinatorAgentDrainAssignmentIsTerminal(assignment));
@@ -2879,7 +4615,8 @@ export function classifySwarmQueueOutcome(input) {
         || action === 'reject'
         || action === 'record-only'
         || input.disposition === 'rejected'
-        || input.mergeReadiness === 'discovery-only') {
+        || input.mergeReadiness === 'discovery-only'
+        || queueOutcomeHas(search, 'research-complete', 'discovery-complete', 'synthesized')) {
         category = 'terminal';
     }
     else if (action === 'rerun'
@@ -3137,6 +4874,8 @@ function terminalOutcomeLabelFromText(value) {
         return 'evidence-only';
     if (token === 'no-change' || token === 'nochange' || token === 'no-op' || token === 'noop' || token === 'unchanged')
         return 'no-change';
+    if (token === 'research-complete' || token === 'discovery-complete' || token === 'synthesized')
+        return 'research-complete';
     if (token === 'generated-by-collector' || token === 'collector-generated' || token === 'generated-collector')
         return 'generated-by-collector';
     if (token === 'patch-missing' || token === 'missing-patch' || token === 'patchmissing')
@@ -3149,7 +4888,7 @@ function terminalOutcomeLabelFromText(value) {
         return 'rejected';
     if (token === 'conflict-blocked' || token === 'merge-conflict' || token === 'textual-conflict' || token === 'conflict')
         return 'conflict-blocked';
-    if (token === 'human-question' || token === 'human-blocked' || token === 'blocked')
+    if (token === 'human-needed' || token === 'human-question' || token === 'human-blocked' || token === 'blocked')
         return 'human-question';
     if (token === 'coordinator-review' || token === 'needs-port' || token === 'escalated' || token === 'review')
         return 'coordinator-review';
@@ -3178,6 +4917,12 @@ export function normalizeSwarmTerminalOutcome(input = {}) {
             || terminalOutcomeTextMatches(input.outcome, 'no-change', 'nochange', 'no-op', 'noop', 'unchanged')
             || terminalOutcomeTextMatches(input.status, 'no-change', 'nochange', 'no-op', 'noop', 'unchanged')
             || terminalOutcomeTextMatches(input.decision, 'no-change', 'nochange', 'no-op', 'noop', 'unchanged');
+    const researchComplete = typeof input === 'string'
+        ? terminalOutcomeTextMatches(input, 'research-complete', 'discovery-complete', 'synthesized')
+        : terminalOutcomeTextMatches(input.label, 'research-complete', 'discovery-complete', 'synthesized')
+            || terminalOutcomeTextMatches(input.outcome, 'research-complete', 'discovery-complete', 'synthesized')
+            || terminalOutcomeTextMatches(input.status, 'research-complete', 'discovery-complete', 'synthesized')
+            || terminalOutcomeTextMatches(input.decision, 'research-complete', 'discovery-complete', 'synthesized');
     const patchMissing = typeof input === 'string'
         ? terminalOutcomeTextMatches(input, 'patch-missing', 'missing-patch', 'patchmissing')
         : input.patchMissing === true
@@ -3200,8 +4945,12 @@ export function normalizeSwarmTerminalOutcome(input = {}) {
             || terminalOutcomeTextMatches(input.status, 'conflict-blocked', 'merge-conflict', 'textual-conflict', 'conflict')
             || terminalOutcomeTextMatches(input.decision, 'conflict-blocked', 'merge-conflict', 'textual-conflict', 'conflict');
     const humanQuestion = typeof input === 'string'
-        ? terminalOutcomeTextMatches(input, 'human-question')
+        ? terminalOutcomeTextMatches(input, 'human-needed', 'human-question')
         : input.humanQuestion === true
+            || terminalOutcomeTextMatches(input.label, 'human-needed')
+            || terminalOutcomeTextMatches(input.outcome, 'human-needed')
+            || terminalOutcomeTextMatches(input.status, 'human-needed')
+            || terminalOutcomeTextMatches(input.decision, 'human-needed')
             || terminalOutcomeTextMatches(input.label, 'human-question')
             || terminalOutcomeTextMatches(input.outcome, 'human-question')
             || terminalOutcomeTextMatches(input.status, 'human-question')
@@ -3227,18 +4976,20 @@ export function normalizeSwarmTerminalOutcome(input = {}) {
             ? 'patch-missing'
             : evidenceOnly
                 ? 'evidence-only'
-                : noChange
-                    ? 'no-change'
-                    : generatedByCollector
-                        ? 'generated-by-collector'
-                        : conflictBlocked
-                            ? 'conflict-blocked'
-                            : humanQuestion || humanBlocked
-                                ? 'human-question'
-                                : coordinatorReview
-                                    ? 'coordinator-review'
-                                    : explicitLabel ?? 'unknown';
-    const category = label === 'applied' || label === 'committed' || label === 'checked' || label === 'superseded' || label === 'evidence-only' || label === 'no-change' || label === 'generated-by-collector'
+                : researchComplete
+                    ? 'research-complete'
+                    : noChange
+                        ? 'no-change'
+                        : generatedByCollector
+                            ? 'generated-by-collector'
+                            : conflictBlocked
+                                ? 'conflict-blocked'
+                                : humanQuestion || humanBlocked
+                                    ? 'human-question'
+                                    : coordinatorReview
+                                        ? 'coordinator-review'
+                                        : explicitLabel ?? 'unknown';
+    const category = label === 'applied' || label === 'committed' || label === 'checked' || label === 'superseded' || label === 'evidence-only' || label === 'no-change' || label === 'research-complete' || label === 'generated-by-collector'
         ? 'success'
         : label === 'patch-missing' || label === 'bundle-missing'
             ? 'incomplete'
@@ -3264,6 +5015,65 @@ export function normalizeSwarmTerminalOutcome(input = {}) {
         ...(typeof input !== 'string' && toJsonObject(input.metadata) ? { metadata: toJsonObject(input.metadata) } : {})
     };
 }
+export function createSwarmTerminalOutcomeRecord(input = {}) {
+    const generatedAt = input.generatedAt ?? Date.now();
+    const queueItemIds = uniqueStrings([input.queueItemId, ...(input.queueItemIds ?? [])]);
+    const subjectId = input.subjectId?.trim()
+        || queueItemIds[0]
+        || input.taskId?.trim()
+        || input.jobId?.trim()
+        || input.id?.trim()
+        || 'unknown-subject';
+    const subjectAliases = uniqueStrings([
+        input.subjectId,
+        ...(input.subjectAliases ?? []),
+        ...queueItemIds,
+        input.taskId,
+        input.jobId
+    ]);
+    const outcome = normalizeSwarmTerminalOutcome(terminalOutcomeInputForRecord(input));
+    const status = terminalOutcomeRecordStatusFromText(input.status)
+        ?? terminalOutcomeRecordStatusFromOutcome(outcome);
+    const reasonCodes = normalizeSwarmTerminalOutcomeReasonCodes([
+        ...(input.reasonCodes ?? []),
+        ...defaultTerminalOutcomeRecordReasonCodes(status)
+    ]);
+    const admitted = input.admitted ?? terminalOutcomeRecordStatusIsAdmitted(status);
+    const evidenceRefs = normalizeNamedRefs(input.evidenceRefs ?? [], 'evidence');
+    return {
+        kind: FRONTIER_SWARM_TERMINAL_OUTCOME_RECORD_KIND,
+        version: FRONTIER_SWARM_TERMINAL_OUTCOME_RECORD_VERSION,
+        id: input.id ?? 'swarm-terminal-outcome-record:' + stableHash([subjectId, subjectAliases, status, reasonCodes, generatedAt]),
+        generatedAt,
+        subjectId,
+        subjectAliases: subjectAliases.length ? subjectAliases : [subjectId],
+        ...(input.jobId ? { jobId: input.jobId } : {}),
+        ...(input.taskId ? { taskId: input.taskId } : {}),
+        ...(input.queueId ? { queueId: input.queueId } : {}),
+        queueItemIds,
+        ...(input.lane ? { lane: input.lane } : {}),
+        ...(input.source ? { source: input.source } : {}),
+        status,
+        outcome,
+        terminal: true,
+        admitted,
+        success: outcome.success,
+        rejected: status === 'rejected',
+        conflict: status === 'conflict',
+        humanNeeded: status === 'human-needed',
+        rerun: status === 'rerun',
+        noChange: status === 'no-change',
+        researchComplete: status === 'research-complete',
+        reasonCodes,
+        reasons: uniqueStrings(input.reasons ?? []),
+        conflictingJobIds: uniqueStrings(input.conflictingJobIds ?? []),
+        supersedes: uniqueStrings(input.supersedes ?? []),
+        ...(input.supersededBy ? { supersededBy: input.supersededBy } : {}),
+        ...(input.rerunOf ? { rerunOf: input.rerunOf } : {}),
+        evidenceRefs,
+        ...(toJsonObject(input.metadata) ? { metadata: toJsonObject(input.metadata) } : {})
+    };
+}
 export function reconcileSwarmTerminalState(input = {}) {
     const generatedAt = input.generatedAt ?? Date.now();
     const doneBucket = input.doneBucket ?? 'done';
@@ -4054,13 +5864,25 @@ function createMergeIndexConflicts(entries) {
                 continue;
             const keys = pairConflictKeys(left, right);
             for (const key of keys) {
-                const kind = key.startsWith('symbol:') ? 'symbol' : key.startsWith('region:') ? 'region' : 'path';
+                const kind = key.startsWith('symbol:')
+                    ? 'symbol'
+                    : key.startsWith('public-contract:')
+                        ? 'public-contract'
+                        : key.startsWith('region:')
+                            ? 'region'
+                            : 'path';
                 const value = key.slice(key.indexOf(':') + 1);
                 conflicts.push({
                     jobIds: [left.jobId, right.jobId].sort(),
                     key,
                     kind,
-                    ...(kind === 'region' ? { region: value } : kind === 'symbol' ? { symbol: value } : { path: value })
+                    ...(kind === 'region'
+                        ? { region: value }
+                        : kind === 'symbol'
+                            ? { symbol: value }
+                            : kind === 'public-contract'
+                                ? { publicContract: value }
+                                : { path: value })
                 });
             }
         }
@@ -4077,6 +5899,9 @@ function pairConflictKeys(left, right) {
     const sharedSymbols = leftKeys.filter((key) => key.startsWith('symbol:') && rightKeySet.has(key));
     if (sharedSymbols.length > 0)
         return sharedSymbols.sort();
+    const sharedPublicContracts = leftKeys.filter((key) => key.startsWith('public-contract:') && rightKeySet.has(key));
+    if (sharedPublicContracts.length > 0)
+        return sharedPublicContracts.sort();
     const leftRegions = leftKeys.filter((key) => key.startsWith('region:'));
     const rightRegions = rightKeys.filter((key) => key.startsWith('region:'));
     if (leftRegions.length > 0 && rightRegions.length > 0) {
@@ -4137,6 +5962,11 @@ function stableIdPart(value) {
         return 'star';
     return normalized.length > 0 ? normalized : 'anonymous';
 }
+function publicContractConflictValue(value) {
+    const trimmed = value.trim();
+    const withoutPrefix = trimmed.startsWith('public-contract:') ? trimmed.slice('public-contract:'.length) : trimmed;
+    return stableIdPart(withoutPrefix);
+}
 function reviewerLaneReasons(entry) {
     const reasons = [];
     if (entry.conflictingJobIds.length)
@@ -4186,6 +6016,154 @@ function ensureMergeQueueScope(scopes, input) {
     scopes.set(scope.id, scope);
     return scope;
 }
+function createSwarmSemanticLeaseScopeMap(scopes, input = {}) {
+    const out = new Map();
+    for (const scope of scopes) {
+        out.set(scope.id, createSwarmSemanticLeaseScopeForMergeQueueScope(scope, { ...input, scopes }));
+    }
+    return out;
+}
+function attachSemanticLeaseScopeToMergeQueueScope(scope, semanticLeaseScopes) {
+    const semanticLeaseScope = semanticLeaseScopes.get(scope.id);
+    return {
+        ...scope,
+        ...(semanticLeaseScope ? { semanticLeaseScope: cloneSemanticLeaseScope(semanticLeaseScope) } : {})
+    };
+}
+function attachSemanticLeaseScopesToAssignment(assignment, semanticLeaseScopes) {
+    const requiredLeaseScopeIds = assignment.requiredLeaseScopeIds?.length ? assignment.requiredLeaseScopeIds : [assignment.scopeId];
+    const requiredSemanticLeaseScopes = requiredLeaseScopeIds
+        .map((scopeId) => semanticLeaseScopes.get(scopeId))
+        .filter((scope) => Boolean(scope))
+        .map(cloneSemanticLeaseScope);
+    const retrySlices = assignment.retrySlices?.map((slice) => {
+        const requiredScopeIds = slice.requiredLeaseScopeIds?.length ? slice.requiredLeaseScopeIds : [slice.scopeId];
+        const requiredScopes = requiredScopeIds
+            .map((scopeId) => semanticLeaseScopes.get(scopeId))
+            .filter((scope) => Boolean(scope))
+            .map(cloneSemanticLeaseScope);
+        const semanticLeaseScope = semanticLeaseScopes.get(slice.scopeId);
+        return {
+            ...slice,
+            ...(semanticLeaseScope ? { semanticLeaseScope: cloneSemanticLeaseScope(semanticLeaseScope) } : {}),
+            ...(requiredScopes.length ? { requiredSemanticLeaseScopes: requiredScopes } : {})
+        };
+    });
+    return {
+        ...assignment,
+        ...(requiredSemanticLeaseScopes.length ? { requiredSemanticLeaseScopes } : {}),
+        ...(retrySlices?.length ? { retrySlices } : {})
+    };
+}
+function semanticLeaseScopesForCoordinatorAssignment(queue, assignment, input = {}) {
+    if (assignment.requiredSemanticLeaseScopes?.length) {
+        return uniqueSemanticLeaseScopes(assignment.requiredSemanticLeaseScopes.map(cloneSemanticLeaseScope));
+    }
+    const queueScopes = new Map(queue.scopes.map((scope) => [scope.id, scope]));
+    const semanticByKey = new Map(createSwarmSemanticLeaseScopesForMergeQueue(queue, input).map((scope) => [scope.key, scope]));
+    const fromIds = coordinatorAssignmentRequiredLeaseScopeIds(assignment)
+        .map((scopeId) => queueScopes.get(scopeId)?.semanticLeaseScope)
+        .filter((scope) => Boolean(scope));
+    if (fromIds.length)
+        return uniqueSemanticLeaseScopes(fromIds);
+    const fromKeys = coordinatorAssignmentRequiredLeaseKeys(assignment, [])
+        .map((key) => semanticByKey.get(key))
+        .filter((scope) => Boolean(scope));
+    if (fromKeys.length)
+        return uniqueSemanticLeaseScopes(fromKeys);
+    const fallbackKey = 'leaseScope' in assignment ? assignment.leaseScope : assignment.leaseKey;
+    return [defineSemanticLeaseScope({
+            kind: 'custom',
+            key: fallbackKey,
+            repository: input.repository,
+            packageId: input.packageId,
+            metadata: mergeSwarmMetadata([
+                toJsonObject(input.metadata),
+                {
+                    swarmQueueId: queue.id,
+                    swarmJobId: assignment.jobId,
+                    fallbackLeaseKey: fallbackKey
+                }
+            ])
+        })];
+}
+function coordinatorAssignmentRequiredLeaseScopeIds(assignment) {
+    const explicit = assignment.requiredLeaseScopeIds ?? [];
+    if (explicit.length)
+        return uniqueStrings(explicit);
+    return uniqueStrings(['queueId' in assignment ? assignment.queueId : assignment.scopeId]);
+}
+function coordinatorAssignmentRequiredLeaseKeys(assignment, scopes) {
+    const explicit = assignment.requiredLeaseKeys ?? [];
+    if (explicit.length)
+        return uniqueStrings(explicit);
+    if (scopes.length)
+        return uniqueStrings(scopes.map((scope) => scope.key));
+    return uniqueStrings(['leaseScope' in assignment ? assignment.leaseScope : assignment.leaseKey]);
+}
+function semanticLeaseScopeOptionsFromMetadata(metadata) {
+    const object = toJsonObject(metadata);
+    if (!object)
+        return {};
+    return {
+        ...(typeof object.repository === 'string' ? { repository: object.repository } : {}),
+        ...(typeof object.packageId === 'string' ? { packageId: object.packageId } : {})
+    };
+}
+function semanticLeaseScopeKindForMergeQueueScope(scope) {
+    if (scope.kind === 'root')
+        return 'repository';
+    if (scope.kind === 'path')
+        return 'path';
+    if (scope.kind === 'lane')
+        return 'lane';
+    if (scope.kind === 'semantic-region' || scope.kind === 'semantic')
+        return semanticLeaseScopeKindForRegion(scope.changedRegions[0]);
+    if (scope.kind === 'package')
+        return 'package';
+    return 'custom';
+}
+function semanticLeaseScopeKindForRegion(region) {
+    if (!region)
+        return 'semantic-region';
+    const normalized = region.toLowerCase();
+    if (normalized.includes(FRONTIER_SWARM_SEMANTIC_OWNERSHIP_EXPORT_STABLE_KEY_KIND) || normalized.includes('named-export') || normalized.includes('default-export'))
+        return 'export';
+    if (normalized.includes(FRONTIER_SWARM_SEMANTIC_OWNERSHIP_TYPE_STABLE_KEY_KIND) || normalized.includes('interface') || normalized.includes('type-alias'))
+        return 'type';
+    if (normalized.includes(FRONTIER_SWARM_SEMANTIC_OWNERSHIP_CLI_COMMAND_STABLE_KEY_KIND))
+        return 'cli-command';
+    if (normalized.includes(FRONTIER_SWARM_SEMANTIC_OWNERSHIP_DOCS_SECTION_STABLE_KEY_KIND))
+        return 'docs-section';
+    if (normalized.includes(FRONTIER_SWARM_SEMANTIC_OWNERSHIP_FIXTURE_FAMILY_STABLE_KEY_KIND))
+        return 'test-fixture';
+    if (normalized.includes(FRONTIER_SWARM_SEMANTIC_OWNERSHIP_TEST_CASE_STABLE_KEY_KIND))
+        return 'test-fixture';
+    if (normalized.includes('function'))
+        return 'function';
+    if (normalized.includes('class'))
+        return 'class';
+    if (normalized.includes('member'))
+        return 'member';
+    return 'semantic-region';
+}
+function semanticLeaseScopeNameForMergeQueueScope(scope) {
+    const region = scope.changedRegions[0];
+    if (region)
+        return region.split(':').filter(Boolean).at(-1);
+    if (scope.changedPaths.length === 1)
+        return scope.changedPaths[0].split('/').at(-1);
+    return scope.title || scope.id;
+}
+function uniqueSemanticLeaseScopes(scopes) {
+    const out = new Map();
+    for (const scope of scopes)
+        out.set(scope.key, cloneSemanticLeaseScope(scope));
+    return Array.from(out.values()).sort((left, right) => left.key.localeCompare(right.key));
+}
+function cloneSemanticLeaseScope(scope) {
+    return cloneJsonValue(scope);
+}
 function mergeQueueRootLeaseKey(rootScopeId) {
     return `merge:root:${rootScopeId}`;
 }
@@ -4300,6 +6278,8 @@ function cloneMergeQueueRetrySlices(slices) {
         leaseKey: slice.leaseKey,
         ...(slice.requiredLeaseScopeIds?.length ? { requiredLeaseScopeIds: [...slice.requiredLeaseScopeIds] } : {}),
         ...(slice.requiredLeaseKeys?.length ? { requiredLeaseKeys: [...slice.requiredLeaseKeys] } : {}),
+        ...(slice.semanticLeaseScope ? { semanticLeaseScope: cloneSemanticLeaseScope(slice.semanticLeaseScope) } : {}),
+        ...(slice.requiredSemanticLeaseScopes?.length ? { requiredSemanticLeaseScopes: slice.requiredSemanticLeaseScopes.map(cloneSemanticLeaseScope) } : {}),
         ...(slice.lane ? { lane: slice.lane } : {}),
         changedPaths: [...slice.changedPaths],
         changedRegions: [...slice.changedRegions],
@@ -4349,6 +6329,7 @@ function createHierarchicalQueueLeaseRecords(input) {
             ...(scope.lane ? { lane: scope.lane } : {}),
             title: scope.title,
             leaseKey: scope.leaseKey,
+            ...(scope.semanticLeaseScope ? { semanticLeaseScope: cloneSemanticLeaseScope(scope.semanticLeaseScope) } : {}),
             ...(hierarchicalQueueLocalLeaderForScope(input, scope) ? { localLeader: hierarchicalQueueLocalLeaderForScope(input, scope) } : {}),
             promotion: {
                 state: promotionState,
@@ -5186,6 +7167,8 @@ function defaultQueueOutcomeForCategory(category, input, search) {
             return 'committed';
         if (action === 'apply-local' || input.decision === 'applied' || queueOutcomeHas(search, 'applied', 'apply-local', 'apply'))
             return 'applied';
+        if (input.decision === 'research-complete' || queueOutcomeHas(search, 'research-complete', 'discovery-complete', 'synthesized'))
+            return 'research-complete';
         if (input.decision === 'checked' || queueOutcomeHas(search, 'checked', 'check'))
             return 'checked';
         if (input.decision === 'superseded' || queueOutcomeHas(search, 'superseded'))
@@ -5249,6 +7232,8 @@ function canonicalizeSwarmQueueOutcome(value) {
         return 'superseded';
     if (token === 'no-change' || token === 'nochange' || token === 'no-op' || token === 'noop' || token === 'unchanged')
         return 'no-change';
+    if (token === 'research-complete' || token === 'discovery-complete' || token === 'synthesized')
+        return 'research-complete';
     if (token === 'rejected' || token === 'reject' || token === 'failed' || token === 'failure')
         return 'rejected';
     if (token === 'rerun' || token === 're-run' || token === 'retry' || token === 'needs-rerun' || token === 'stale-rerun')
@@ -5263,6 +7248,96 @@ function canonicalizeSwarmQueueOutcome(value) {
         return 'closed';
     return undefined;
 }
+function terminalOutcomeInputForRecord(input) {
+    if (input.outcome && typeof input.outcome === 'object')
+        return input.outcome;
+    return {
+        label: input.label,
+        outcome: typeof input.outcome === 'string' ? input.outcome : undefined,
+        status: input.status,
+        decision: input.decision,
+        reasons: input.reasons,
+        metadata: input.metadata
+    };
+}
+function terminalOutcomeRecordStatusFromText(value) {
+    const normalized = normalizeOptionalString(value);
+    if (!normalized)
+        return undefined;
+    const token = normalizeSwarmTerminalOutcomeText(normalized);
+    if (token === 'applied' || token === 'apply-local' || token === 'apply' || token === 'committed' || token === 'commit' || token === 'checked' || token === 'check')
+        return 'applied';
+    if (token === 'rejected' || token === 'reject' || token === 'failed' || token === 'failure')
+        return 'rejected';
+    if (token === 'superseded')
+        return 'superseded';
+    if (token === 'no-change' || token === 'nochange' || token === 'no-op' || token === 'noop' || token === 'unchanged' || token === 'recorded' || token === 'closed' || token === 'evidence-only' || token === 'evidenceonly' || token === 'generated-by-collector')
+        return 'no-change';
+    if (token === 'conflict' || token === 'conflict-blocked' || token === 'merge-conflict' || token === 'textual-conflict')
+        return 'conflict';
+    if (token === 'human-needed' || token === 'human-question' || token === 'human-blocked' || token === 'blocked' || token === 'coordinator-review' || token === 'needs-port' || token === 'escalated' || token === 'review')
+        return 'human-needed';
+    if (token === 'research-complete' || token === 'discovery-complete' || token === 'synthesized')
+        return 'research-complete';
+    if (token === 'rerun' || token === 're-run' || token === 'retry' || token === 'needs-rerun' || token === 'stale-rerun')
+        return 'rerun';
+    return token;
+}
+function terminalOutcomeRecordStatusFromOutcome(outcome) {
+    return terminalOutcomeRecordStatusFromText(outcome.label)
+        ?? terminalOutcomeRecordStatusFromText(outcome.category)
+        ?? 'no-change';
+}
+function terminalOutcomeRecordStatusIsAdmitted(status) {
+    return status === 'applied'
+        || status === 'superseded'
+        || status === 'no-change'
+        || status === 'research-complete';
+}
+function defaultTerminalOutcomeRecordReasonCodes(status) {
+    if (status === 'applied')
+        return ['accepted-by-admission'];
+    if (status === 'rejected')
+        return ['failed-verification'];
+    if (status === 'superseded')
+        return ['superseded-by-newer-output'];
+    if (status === 'no-change')
+        return ['no-effective-change'];
+    if (status === 'conflict')
+        return ['conflict-detected'];
+    if (status === 'human-needed')
+        return ['human-decision-required'];
+    if (status === 'research-complete')
+        return ['research-complete'];
+    if (status === 'rerun')
+        return ['stale-rerun-required'];
+    return [];
+}
+function normalizeSwarmTerminalOutcomeReasonCodes(reasonCodes) {
+    return uniqueStrings(uniqueStrings(reasonCodes).map(canonicalizeSwarmTerminalOutcomeReasonCode));
+}
+function canonicalizeSwarmTerminalOutcomeReasonCode(value) {
+    const token = normalizeSwarmTerminalOutcomeText(value);
+    if (!token)
+        return value;
+    if (token === 'accepted' || token === 'admitted' || token === 'accepted-by-admission')
+        return 'accepted-by-admission';
+    if (token === 'failed' || token === 'failed-verification' || token === 'verification-failed')
+        return 'failed-verification';
+    if (token === 'superseded' || token === 'superseded-by-newer-output')
+        return 'superseded-by-newer-output';
+    if (token === 'no-change' || token === 'nochange' || token === 'no-effective-change')
+        return 'no-effective-change';
+    if (token === 'conflict' || token === 'conflict-detected' || token === 'merge-conflict')
+        return 'conflict-detected';
+    if (token === 'human-needed' || token === 'human-decision-required' || token === 'human-question')
+        return 'human-decision-required';
+    if (token === 'research-complete' || token === 'discovery-complete')
+        return 'research-complete';
+    if (token === 'rerun' || token === 'stale-rerun-required' || token === 'needs-rerun')
+        return 'stale-rerun-required';
+    return token;
+}
 function queueOutcomeInputsFromMergeQueue(queue) {
     return queue.assignments.map((assignment) => ({
         subjectAliases: uniqueStrings([assignment.taskId, assignment.jobId, ...assignment.queueItemIds]),
@@ -5420,6 +7495,7 @@ function queueOutcomeDecisionIsResolvedOutput(decision) {
         || decision.outcome === 'checked'
         || decision.outcome === 'superseded'
         || decision.outcome === 'no-change'
+        || decision.outcome === 'research-complete'
         || decision.outcome === 'recorded'
         || decision.outcome === 'closed';
 }
@@ -5867,6 +7943,253 @@ function countBy(values) {
         out[value] = (out[value] ?? 0) + 1;
     return out;
 }
+const FRONTIER_SWARM_BLOCKING_MERGE_CANDIDATE_REASON_CODES = new Set([
+    'missing-sidecar',
+    'empty-sidecar',
+    'stale-source-hash',
+    'symbol-conflict',
+    'effect-conflict'
+]);
+const FRONTIER_SWARM_REVIEW_MERGE_CANDIDATE_REASON_CODES = new Set([
+    'tests-missing'
+]);
+const FRONTIER_SWARM_CONFLICT_MERGE_CANDIDATE_REASON_CODES = new Set([
+    'symbol-conflict',
+    'effect-conflict'
+]);
+function isSwarmSemanticChange(input) {
+    return input.kind === FRONTIER_SWARM_SEMANTIC_CHANGE_KIND;
+}
+function isSwarmMergeCandidate(input) {
+    return input.kind === FRONTIER_SWARM_MERGE_CANDIDATE_KIND;
+}
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function normalizeSwarmMergeCandidateReasonCodes(reasonCodes) {
+    return uniqueStrings(reasonCodes);
+}
+function normalizeSwarmSourceSpan(input, fallback = {}) {
+    const metadata = toJsonObject(input?.metadata);
+    const startLine = readNonNegativeNumber(input?.startLine);
+    const startColumn = readNonNegativeNumber(input?.startColumn);
+    const endLine = readNonNegativeNumber(input?.endLine);
+    const endColumn = readNonNegativeNumber(input?.endColumn);
+    const startOffset = readNonNegativeNumber(input?.startOffset);
+    const endOffset = readNonNegativeNumber(input?.endOffset);
+    const path = normalizeOptionalString(input?.path) ?? normalizeOptionalString(fallback.sourcePath);
+    const sourceHash = normalizeOptionalString(input?.sourceHash) ?? normalizeOptionalString(fallback.sourceHash);
+    const expectedSourceHash = normalizeOptionalString(input?.expectedSourceHash) ?? normalizeOptionalString(fallback.expectedSourceHash);
+    return {
+        ...(path ? { path } : {}),
+        ...(startLine !== undefined ? { startLine: Math.floor(startLine) } : {}),
+        ...(startColumn !== undefined ? { startColumn: Math.floor(startColumn) } : {}),
+        ...(endLine !== undefined ? { endLine: Math.floor(endLine) } : {}),
+        ...(endColumn !== undefined ? { endColumn: Math.floor(endColumn) } : {}),
+        ...(startOffset !== undefined ? { startOffset: Math.floor(startOffset) } : {}),
+        ...(endOffset !== undefined ? { endOffset: Math.floor(endOffset) } : {}),
+        ...(sourceHash ? { sourceHash } : {}),
+        ...(expectedSourceHash ? { expectedSourceHash } : {}),
+        ...(metadata ? { metadata } : {})
+    };
+}
+function deriveSwarmSemanticChangeReasonCodes(input, sourceSpan) {
+    const reasons = [];
+    if (input.conflictReason)
+        reasons.push(input.conflictReason);
+    if (sourceSpan.sourceHash && sourceSpan.expectedSourceHash && sourceSpan.sourceHash !== sourceSpan.expectedSourceHash) {
+        reasons.push('stale-source-hash');
+    }
+    return normalizeSwarmMergeCandidateReasonCodes(reasons);
+}
+function deriveSwarmMergeCandidateReasonCodes(input, semanticChanges, sourceSpan) {
+    const reasons = [];
+    if (input.sidecarRequired && !input.sidecarPath)
+        reasons.push('missing-sidecar');
+    if (input.sidecarEmpty)
+        reasons.push('empty-sidecar');
+    if (input.hasLosses)
+        reasons.push('lossy-import');
+    if (input.testsRequired && input.testsPassed !== true)
+        reasons.push('tests-missing');
+    if (input.conflictReason)
+        reasons.push(input.conflictReason);
+    if (sourceSpan.sourceHash && sourceSpan.expectedSourceHash && sourceSpan.sourceHash !== sourceSpan.expectedSourceHash) {
+        reasons.push('stale-source-hash');
+    }
+    if (semanticChanges.length === 0 && input.sidecarPath)
+        reasons.push('empty-sidecar');
+    return normalizeSwarmMergeCandidateReasonCodes(reasons);
+}
+function normalizeSwarmSemanticConfidence(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return clamp01(value);
+    const normalized = normalizeOptionalString(value);
+    return normalized ?? 'medium';
+}
+function normalizeSwarmConflictReason(conflictReason, reasonCodes) {
+    const explicit = normalizeOptionalString(conflictReason);
+    if (explicit)
+        return explicit;
+    return reasonCodes.find((reason) => FRONTIER_SWARM_CONFLICT_MERGE_CANDIDATE_REASON_CODES.has(reason));
+}
+function normalizeGraphNode(input, generatedAt = Date.now()) {
+    const metadata = toJsonObject(input.metadata);
+    const id = input.id ?? graphNodeId(input.kind, input.title ?? input.jobId ?? input.taskId ?? String(generatedAt));
+    return {
+        id,
+        kind: input.kind,
+        ...(input.title ? { title: input.title } : {}),
+        ...(input.status ? { status: input.status } : {}),
+        ...(input.jobId ? { jobId: input.jobId } : {}),
+        ...(input.taskId ? { taskId: input.taskId } : {}),
+        ...(input.path ? { path: input.path } : {}),
+        generatedAt: input.generatedAt ?? generatedAt,
+        ...(metadata ? { metadata } : {})
+    };
+}
+function normalizeGraphEdge(input, generatedAt = Date.now()) {
+    const metadata = toJsonObject(input.metadata);
+    return {
+        id: input.id ?? `${input.kind}:${input.from}->${input.to}`,
+        from: input.from,
+        to: input.to,
+        kind: input.kind,
+        ...(input.label ? { label: input.label } : {}),
+        generatedAt: input.generatedAt ?? generatedAt,
+        ...(metadata ? { metadata } : {})
+    };
+}
+function normalizeGraphEvent(input, generatedAt = Date.now()) {
+    const timestamp = input.timestamp ?? generatedAt;
+    const metadata = toJsonObject(input.metadata);
+    return {
+        id: input.id ?? 'swarm-graph-event:' + stableHash([input.type, input.nodeId, input.edgeId, timestamp]),
+        type: input.type,
+        ...(input.nodeId ? { nodeId: input.nodeId } : {}),
+        ...(input.edgeId ? { edgeId: input.edgeId } : {}),
+        timestamp,
+        ...(metadata ? { metadata } : {})
+    };
+}
+function isPassingGraphStatus(status) {
+    return status === 'passed' || status === 'accepted' || status === 'verified' || status === 'completed';
+}
+function isBlockingGraphStatus(status) {
+    return status === 'failed' || status === 'rejected' || status === 'blocked';
+}
+function dedupeGraphNodes(nodes) {
+    const byId = new Map();
+    for (const node of nodes)
+        byId.set(node.id, mergeGraphNode(byId.get(node.id), node));
+    return Array.from(byId.values()).sort((left, right) => left.id.localeCompare(right.id));
+}
+function mergeGraphNode(existing, node) {
+    if (!existing)
+        return node;
+    return {
+        ...existing,
+        ...node,
+        metadata: mergeGraphMetadata(existing.metadata, node.metadata)
+    };
+}
+function dedupeGraphEdges(edges) {
+    const byId = new Map();
+    for (const edge of edges)
+        byId.set(edge.id, edge);
+    return Array.from(byId.values()).sort((left, right) => left.id.localeCompare(right.id));
+}
+function summarizeSwarmRunGraph(nodes, edges, events) {
+    return {
+        nodeCount: nodes.length,
+        edgeCount: edges.length,
+        eventCount: events.length,
+        nodeKinds: countBy(nodes.map((node) => node.kind)),
+        edgeKinds: countBy(edges.map((edge) => edge.kind)),
+        openBlockerCount: nodes.filter((node) => node.status === 'blocked').length + edges.filter((edge) => edge.kind === 'blocks').length,
+        humanQuestionCount: nodes.filter((node) => node.kind === 'decision' && /human|question/i.test(node.title ?? '')).length
+    };
+}
+function graphNodeId(kind, value) {
+    return `${kind}:${normalizeGraphIdPart(value)}`;
+}
+function normalizeGraphIdPart(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9_.:-]+/g, '-').replace(/^-+|-+$/g, '') || stableHash(value);
+}
+function normalizeSwarmGraphRef(input) {
+    return {
+        id: input.id ?? 'swarm-graph-ref:' + stableHash([input.kind, input.graphId, input.nodeId, input.edgeId, input.role]),
+        kind: input.kind ?? 'graph',
+        ...(input.graphId ? { graphId: input.graphId } : {}),
+        ...(input.nodeId ? { nodeId: input.nodeId } : {}),
+        ...(input.edgeId ? { edgeId: input.edgeId } : {}),
+        ...(input.role ? { role: input.role } : {}),
+        ...(toJsonObject(input.metadata) ? { metadata: toJsonObject(input.metadata) } : {})
+    };
+}
+function normalizeSwarmGraphRefs(input) {
+    return input.map(normalizeSwarmGraphRef).sort((left, right) => left.id.localeCompare(right.id));
+}
+function normalizeSwarmPatchEvent(input, replayRecordId, index) {
+    if (isSwarmPatchEvent(input) && (!replayRecordId || input.replayRecordId) && (index === undefined || input.sequence !== undefined)) {
+        return input;
+    }
+    return createSwarmPatchEvent({
+        ...input,
+        replayRecordId: input.replayRecordId ?? replayRecordId,
+        sequence: input.sequence ?? index
+    });
+}
+function inferImprovementLoopStatus(input) {
+    if (input.result !== undefined)
+        return 'applied';
+    if (input.action !== undefined)
+        return 'planned';
+    if (input.observation !== undefined)
+        return 'observed';
+    return 'unknown';
+}
+function createImprovementLoopPhaseNode(loop, phase, value, generatedAt) {
+    return {
+        id: graphNodeId('rsi', `${loop.id}:${phase}`),
+        kind: 'rsi',
+        title: `${loop.title} ${phase}`,
+        status: loop.status,
+        jobId: loop.jobId,
+        taskId: loop.taskId,
+        generatedAt,
+        metadata: {
+            phase,
+            value,
+            loop
+        }
+    };
+}
+function isSwarmGateRecord(input) {
+    return input.kind === FRONTIER_SWARM_GATE_RECORD_KIND;
+}
+function isSwarmEvidenceRecord(input) {
+    return input.kind === FRONTIER_SWARM_EVIDENCE_RECORD_KIND;
+}
+function isSwarmPatchEvent(input) {
+    return input.kind === FRONTIER_SWARM_PATCH_EVENT_KIND;
+}
+function isSwarmReplayRecord(input) {
+    return input.kind === FRONTIER_SWARM_REPLAY_RECORD_KIND;
+}
+function isSwarmImprovementLoop(input) {
+    return input.kind === FRONTIER_SWARM_IMPROVEMENT_LOOP_KIND;
+}
+function mergeGraphMetadata(left, right) {
+    if (!left)
+        return right;
+    if (!right)
+        return left;
+    return { ...left, ...right };
+}
 function hasJobDependencyCycle(start, dependenciesByJobId) {
     const visiting = new Set();
     const visited = new Set();
@@ -8123,6 +10446,141 @@ function joinPathParts(...parts) {
         .filter(Boolean)
         .join('/');
 }
+function swarmRunEventTime(options, fallback) {
+    if (options.time)
+        return options.time;
+    const value = options.now ?? fallback;
+    return new Date(Number.isFinite(value) ? value : Date.now()).toISOString();
+}
+function isFrontierRunEventList(input) {
+    return Array.isArray(input);
+}
+function swarmRunLaneNodeId(lane) {
+    return String(lane).startsWith('lane:') ? String(lane) : `lane:${lane}`;
+}
+function swarmRunTaskNodeId(taskId) {
+    return String(taskId).startsWith('task:') ? String(taskId) : `task:${taskId}`;
+}
+function swarmRunAttemptNodeId(jobId) {
+    return String(jobId).startsWith('attempt:') ? String(jobId) : `attempt:${jobId}`;
+}
+function swarmRunLeaseNodeId(leaseId) {
+    return String(leaseId).startsWith('lease:') ? String(leaseId) : `lease:${leaseId}`;
+}
+function swarmRunPatchNodeId(jobId) {
+    return String(jobId).startsWith('patch:') ? String(jobId) : `patch:${jobId}`;
+}
+function swarmRunArtifactNodeId(artifactPath) {
+    return `artifact:${slug(artifactPath)}:${stableHash(artifactPath).slice('fnv1a32:'.length)}`;
+}
+function swarmRunEvidenceNodeId(jobId, evidencePath) {
+    return `evidence:${slug(jobId)}:${stableHash(evidencePath).slice('fnv1a32:'.length)}`;
+}
+function swarmRunVerificationNodeId(jobId, index, name) {
+    return `verification:${slug(jobId)}:${index}:${slug(name || 'command')}`;
+}
+function swarmRunDecisionNodeId(id) {
+    return String(id).startsWith('decision:') ? String(id) : `decision:${id}`;
+}
+function inferSwarmLanePackageId(jobs) {
+    for (const job of jobs) {
+        const candidate = job.task.metadata?.packageId ?? job.metadata?.packageId ?? job.task.metadata?.package ?? job.metadata?.package;
+        if (typeof candidate === 'string' && candidate)
+            return candidate;
+    }
+    return undefined;
+}
+function formatSwarmCommandLine(command) {
+    return [command.command, ...command.args].join(' ');
+}
+function swarmStatusToRunStatus(status) {
+    if (status === 'completed' || status === 'verified')
+        return 'done';
+    if (status === 'failed' || status === 'rejected')
+        return 'rejected';
+    if (status === 'blocked')
+        return 'blocked';
+    if (status === 'running')
+        return 'running';
+    if (status === 'planned')
+        return 'planned';
+    return 'ready';
+}
+function swarmResultStatusToAttemptStatus(status) {
+    if (status === 'completed' || status === 'verified')
+        return 'completed';
+    if (status === 'running')
+        return 'running';
+    if (status === 'cancelled')
+        return 'cancelled';
+    if (status === 'timed-out' || status === 'timeout')
+        return 'timed-out';
+    if (status === 'queued' || status === 'ready' || status === 'planned')
+        return 'queued';
+    return 'failed';
+}
+function swarmRiskToRunRisk(risk) {
+    if (risk === 'low' || risk === 'medium' || risk === 'high')
+        return risk;
+    return 'medium';
+}
+function inferSwarmArtifactType(file) {
+    const lower = file.toLowerCase();
+    if (lower.endsWith('.patch') || lower.endsWith('.diff'))
+        return 'patch';
+    if (lower.endsWith('.json') || lower.endsWith('.jsonl'))
+        return 'json';
+    if (lower.endsWith('.log') || lower.endsWith('.txt') || lower.includes('stdout') || lower.includes('stderr'))
+        return 'log';
+    if (lower.endsWith('.png') || lower.endsWith('.jpg') || lower.endsWith('.jpeg') || lower.endsWith('.webp'))
+        return 'image';
+    return 'artifact';
+}
+function swarmDispositionToRunDecision(disposition, readiness) {
+    if (disposition === 'auto-mergeable' || readiness === 'verified-patch')
+        return 'apply';
+    if (disposition === 'stale-against-head')
+        return 'rerun';
+    if (disposition === 'rejected' || readiness === 'rejected')
+        return 'reject';
+    if (disposition === 'needs-port' || disposition === 'blocked' || readiness === 'blocked')
+        return 'human-question';
+    return 'record-only';
+}
+function swarmQueueOutcomeToRunDecision(decision) {
+    if (decision.outcome === 'applied' || decision.decision === 'applied' || decision.action === 'apply-local')
+        return 'apply';
+    if (decision.outcome === 'rerun' || decision.decision === 'rerun' || decision.staleOrRerun)
+        return 'rerun';
+    if (decision.outcome === 'rejected' || decision.decision === 'rejected')
+        return 'reject';
+    if (decision.action === 'promote')
+        return 'promote';
+    if (decision.humanBlocked || decision.outcome === 'human-blocked')
+        return 'human-question';
+    return 'record-only';
+}
+function swarmQueueOutcomeRequiredActions(decision) {
+    const actions = [];
+    if (decision.coordinatorReview || decision.reviewDebt)
+        actions.push('coordinator-review');
+    if (decision.humanBlocked)
+        actions.push('human-answer');
+    if (decision.staleOrRerun)
+        actions.push('rerun');
+    if (decision.conflict)
+        actions.push('resolve-conflict');
+    return uniqueStrings(actions);
+}
+function pruneUndefinedJsonObject(value) {
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry === undefined)
+            continue;
+        out[key] = toJsonValue(entry);
+    }
+    return out;
+}
 function normalizeId(value, label) {
     const id = String(value || '').trim();
     if (!id)