@shapeshift-labs/frontier-swarm 0.3.0 → 0.4.0

package/README.md

@@ -36,7 +36,7 @@ The published Frontier package family is generated from one shared package catal
 - [`@shapeshift-labs/frontier-workflow`](https://www.npmjs.com/package/@shapeshift-labs/frontier-workflow): Serializable durable workflow/process manifests for Frontier apps, including steps, waits, approvals, timers, retries, expected patches, compensation, records, timelines, and registry graph output.
 - [`@shapeshift-labs/frontier-worker`](https://www.npmjs.com/package/@shapeshift-labs/frontier-worker): Serializable worker and edge task descriptors for Frontier apps, including queues, idempotency keys, retry and timeout policy, declared reads/writes/effects, snapshots, patch outputs, produced assets, execution records, logs, trace links, proof hashes, dedupe indexes, and registry graph output.
 - [`@shapeshift-labs/frontier-queue`](https://www.npmjs.com/package/@shapeshift-labs/frontier-queue): Serializable durable queue state, leases, retries, dedupe keys, patch-carrying jobs, dead-letter records, replay evidence, and queue inspection for Frontier apps.
-- [`@shapeshift-labs/frontier-swarm-codex`](https://www.npmjs.com/package/@shapeshift-labs/frontier-swarm-codex): Node Codex CLI adapter for Frontier swarm plans, including prompt rendering, worktree and snapshot workspaces, Codex argument compatibility, JSONL capture, verification commands, pid-backed stop, collect buckets, merge bundles, and result artifacts.
+- [`@shapeshift-labs/frontier-swarm-codex`](https://www.npmjs.com/package/@shapeshift-labs/frontier-swarm-codex): Node Codex CLI adapter for Frontier swarm plans, including prompt rendering, worktree and snapshot workspaces, Codex argument compatibility, JSONL capture, verification commands, pid-backed stop, collect/apply workflows, merge indexes, queue overlays, merge bundles, and result artifacts.
 - [`@shapeshift-labs/frontier-kv`](https://www.npmjs.com/package/@shapeshift-labs/frontier-kv): Serializable in-memory key/value state for Frontier apps, including TTL, versioned compare-and-set, batched patch mutations, scans, watchers, snapshots, JSONL event evidence, and replay verification.
 - [`@shapeshift-labs/frontier-kv-locks`](https://www.npmjs.com/package/@shapeshift-labs/frontier-kv-locks): Lease-style lock records on top of Frontier KV, including acquire, renew, release, fencing tokens, expiration, owner evidence, and replayable lock events.
 - [`@shapeshift-labs/frontier-kv-rate-limit`](https://www.npmjs.com/package/@shapeshift-labs/frontier-kv-rate-limit): Patch-native rate limit buckets for Frontier KV, including fixed windows, sliding windows, token buckets, deterministic refill, consume evidence, and reset records.
@@ -248,8 +248,19 @@ The scale APIs are runtime-neutral and serializable:
 - `createSwarmReviewPlan` samples or requires reviewer assignments,
 - `createSwarmMergePlan` blocks jobs with failed checks, required reviews, ownership violations, or conflicting changed paths,
 - job results include merge-readiness classification: `discovery-only`, `patch-candidate`, `verified-patch`, `rejected`, or `blocked`,
-- `ownershipRegions` allow hot files to be split into semantic regions such as `content.docs.*` or `adminSettings.quota.*`; merge conflict detection prefers changed regions when workers report them,
+- `ownershipRegions` allow hot files to be split into semantic regions such as `content.docs.*` or `adminSettings.quota.*`; merge conflict detection compares explicit changed regions when both sides report them and falls back to path conflicts when either side omits regions,
 - `createSwarmMergeBundle` builds a compact worker `merge.json` shape with touched owned files, patch path, evidence, verification, queue items satisfied, risk, and disposition,
+- `createSwarmQueueOverlay` and `deriveSwarmQueueStatus` keep central queue files immutable while deriving status from worker result overlays,
+- `createSwarmMergeIndex` records stale/patch status and region-aware conflicts so coordinators can review ready bundles before reading every worker directory,
+- `checkSwarmRegionOwnership` makes semantic region ownership enforceable instead of only advisory,
+- `createSwarmHotspotReport` highlights repeatedly touched files and suggests module/region splits for merge throughput,
+- `createSwarmReviewerLanePlan` turns risky/conflicting merge bundles into reviewer-lane tasks,
+- `createSwarmRunStoreShards` describes sharded event/result/checkpoint paths for large run stores,
+- `createSwarmMergeAdmission` limits ready merges by count, touched paths/regions, and risk budget,
+- `createSwarmPatchStackPlan` clusters compatible bundles into candidate patch stacks by lane, path, region, disposition, and risk so reviewers can evaluate batches instead of individual worker directories,
+- `createSwarmContextPack` gives workers compact task context: relevant files, API maps, known failures, focused/oracle commands, expected evidence, exclusions, evidence schema, playbooks, and explicit dead ends to avoid,
+- `createSwarmOracleCorpus` indexes deterministic reference artifacts such as traces, snapshots, classifications, expected outputs, or fixtures without assuming a project domain,
+- `createSwarmLanePlaybook` turns successful prior bundles into persistent lane-specific guidance with commands, hot paths, evidence patterns, and avoid-investigating notes,
 - `decomposeSwarmFeature` creates an initial task queue for feature work across lanes.
 
 ## Hierarchical Compute
@@ -273,13 +284,18 @@ That lets a parent swarm route implementation jobs to a deep model while evidenc
 - `createSwarmPlan`, `createSwarmRun`
 - `createSwarmSchedule`, `createSwarmLeases`
 - `createSwarmQueueSnapshot`, `createSwarmRunCheckpoint`
+- `createSwarmQueueOverlay`, `deriveSwarmQueueStatus`
 - `createSwarmEventStream`, `createSwarmMailbox`, `routeSwarmEventToMailboxes`
 - `checkSwarmBudget`
 - `createSwarmArtifactIndex`
-- `createSwarmReviewPlan`, `createSwarmMergePlan`
+- `createSwarmReviewPlan`, `createSwarmReviewerLanePlan`, `createSwarmMergePlan`
 - `createSwarmMergeBundle`
+- `createSwarmMergeIndex`, `createSwarmMergeAdmission`
+- `createSwarmHotspotReport`, `createSwarmRunStoreShards`
+- `createSwarmPatchStackPlan`
+- `createSwarmContextPack`, `createSwarmOracleCorpus`, `createSwarmLanePlaybook`
 - `classifySwarmMergeReadiness`, `classifySwarmMergeDisposition`
-- `resolveSwarmChangedRegions`
+- `resolveSwarmChangedRegions`, `checkSwarmRegionOwnership`
 - `decomposeSwarmFeature`
 - `recordSwarmEvent`, `completeSwarmJob`
 - `resolveSwarmCompute`
@@ -295,7 +311,7 @@ Run the package-local benchmark:
 npm run bench
 ```
 
-The benchmark writes `benchmarks/results/frontier-swarm-package-bench-latest.json` when run from the monorepo. These are Frontier-only package measurements for plan creation, manifest validation, hierarchical compute resolution, ownership checks, scheduling/leases, queue snapshots, merge bundle creation, event routing, run checkpoints, JSONL, and proof hashing.
+The benchmark writes `benchmarks/results/frontier-swarm-package-bench-latest.json` when run from the monorepo. These are Frontier-only package measurements for plan creation, manifest validation, hierarchical compute resolution, ownership checks, scheduling/leases, queue snapshots, queue overlays, merge bundles, merge indexes, merge admission, hotspot reports, context packs, oracle corpora, lane playbooks, patch stack plans, event routing, run checkpoints, JSONL, and proof hashing.
 
 ## Source Repository
 

package/benchmarks/package-bench.mjs

@@ -4,12 +4,20 @@ import { performance } from 'node:perf_hooks';
 import { fileURLToPath } from 'node:url';
 import {
   checkSwarmOwnership,
+  createSwarmContextPack,
+  createSwarmHotspotReport,
+  createSwarmLanePlaybook,
+  createSwarmMergeAdmission,
   createSwarmManifest,
   createSwarmEventStream,
   createSwarmLeases,
   createSwarmMergeBundle,
+  createSwarmMergeIndex,
+  createSwarmOracleCorpus,
+  createSwarmPatchStackPlan,
   createSwarmPlan,
   createSwarmProof,
+  createSwarmQueueOverlay,
   createSwarmQueueSnapshot,
   createSwarmRun,
   createSwarmRunCheckpoint,
@@ -41,6 +49,8 @@ let cursor = 0;
 let schedule = createSwarmSchedule({ plan, maxReadyJobs: 128 });
 let leases = createSwarmLeases({ schedule, workerId: 'bench-worker', now: 1000, leaseMs: 60000, count: 16 });
 let eventStream = createSwarmEventStream({ runId: 'bench', root: 'agent-runs/bench/streams', lanes: manifest.lanes });
+let bundles = makeBundles(plan, 32);
+let mergeIndex = createSwarmMergeIndex({ bundles });
 
 const rows = [
   measure('create-plan-' + taskCount, 8, () => {
@@ -80,6 +90,45 @@ const rows = [
     },
     patchPath: 'agent-runs/bench/changes.patch'
   }).id.length),
+  measure('queue-overlay-' + taskCount, 16, () => createSwarmQueueOverlay({ bundles, generatedAt: 3000 + cursor++ }).summary.entryCount),
+  measure('merge-index-' + taskCount, 8, () => {
+    bundles = makeBundles(plan, 32);
+    mergeIndex = createSwarmMergeIndex({ bundles, generatedAt: 4000 + cursor++ });
+    return mergeIndex.summary.entryCount + mergeIndex.summary.conflictCount;
+  }),
+  measure('merge-admission-' + taskCount, 16, () => createSwarmMergeAdmission({ index: mergeIndex, maxReady: 8, maxChangedPaths: 16 }).summary.admittedCount),
+  measure('hotspot-report-' + taskCount, 16, () => createSwarmHotspotReport({ bundles, threshold: 3 }).summary.recommendationCount),
+  measure('context-pack-' + taskCount, 32, () => createSwarmContextPack({
+    job: plan.jobs[cursor % plan.jobs.length],
+    files: ['src/runtime/file.ts', 'test/runtime-smoke.mjs'],
+    apiMap: {
+      runtime: ['createRuntime', 'stepRuntime'],
+      tests: ['runtime smoke gate']
+    },
+    knownFailures: ['shared renderer gate is noisy on old snapshots'],
+    oracleCommands: [{ name: 'focused-gate', command: 'npm', args: ['test'], required: true }],
+    evidenceSchema: { type: 'object', required: ['ok', 'commands'] },
+    avoidInvestigating: ['unrelated route snapshots'],
+    playbookIds: ['runtime-playbook']
+  }).files.length),
+  measure('oracle-corpus-' + taskCount, 32, () => createSwarmOracleCorpus({
+    artifacts: [
+      { id: 'trace-runtime', path: 'oracles/runtime-trace.jsonl', kind: 'trace', tags: ['runtime', 'reference'], hash: 'fnv1a32:trace' },
+      { id: 'snapshot-routing', path: 'oracles/routing-snapshot.json', kind: 'snapshot', tags: ['routing', 'reference'] }
+    ]
+  }).summary.artifactCount),
+  measure('lane-playbook-' + taskCount, 16, () => createSwarmLanePlaybook({
+    lane: 'runtime',
+    successfulBundles: bundles,
+    notes: ['prefer narrow patches with focused evidence'],
+    commands: [{ name: 'runtime-smoke', command: 'npm', args: ['test'], required: true }],
+    avoidInvestigating: ['generated fixtures unless task owns them'],
+    evidencePatterns: ['evidence.json', 'commands.md']
+  }).successfulJobIds.length),
+  measure('patch-stack-plan-' + taskCount, 16, () => createSwarmPatchStackPlan({
+    index: mergeIndex,
+    maxStackSize: 8
+  }).summary.stackCount),
   measure('event-route-' + taskCount, 64, () => {
     eventStream = createSwarmEventStream({ runId: 'bench', root: 'agent-runs/bench/streams', lanes: manifest.lanes });
     return routeSwarmEventToMailboxes(eventStream, { type: 'agent.evidence', jobId: plan.jobs[cursor++ % plan.jobs.length].id, lane: 'runtime' }).length;
@@ -146,6 +195,25 @@ function makeTasks(count) {
   return tasks;
 }
 
+function makeBundles(plan, count) {
+  const bundles = [];
+  for (let i = 0; i < Math.min(count, plan.jobs.length); i += 1) {
+    const job = plan.jobs[i];
+    bundles.push(createSwarmMergeBundle({
+      job,
+      result: {
+        jobId: job.id,
+        status: 'verified',
+        changedPaths: [job.task.targetRefs[0] ?? `src/runtime/file-${i}.ts`],
+        changedRegions: i % 2 === 0 ? [`region.${i}`] : [],
+        verification: [{ status: 0 }]
+      },
+      patchPath: `agent-runs/bench/${job.id}/changes.patch`
+    }));
+  }
+  return bundles;
+}
+
 function measure(fixture, operationsPerRound, fn) {
   const samples = [];
   let checksum = 0;

package/dist/index.d.ts

@@ -31,6 +31,26 @@ export declare const FRONTIER_SWARM_MERGE_PLAN_KIND = "frontier.swarm.merge-plan
 export declare const FRONTIER_SWARM_MERGE_PLAN_VERSION = 1;
 export declare const FRONTIER_SWARM_MERGE_BUNDLE_KIND = "frontier.swarm.merge-bundle";
 export declare const FRONTIER_SWARM_MERGE_BUNDLE_VERSION = 1;
+export declare const FRONTIER_SWARM_QUEUE_OVERLAY_KIND = "frontier.swarm.queue-overlay";
+export declare const FRONTIER_SWARM_QUEUE_OVERLAY_VERSION = 1;
+export declare const FRONTIER_SWARM_MERGE_INDEX_KIND = "frontier.swarm.merge-index";
+export declare const FRONTIER_SWARM_MERGE_INDEX_VERSION = 1;
+export declare const FRONTIER_SWARM_HOTSPOT_REPORT_KIND = "frontier.swarm.hotspot-report";
+export declare const FRONTIER_SWARM_HOTSPOT_REPORT_VERSION = 1;
+export declare const FRONTIER_SWARM_REVIEWER_LANE_PLAN_KIND = "frontier.swarm.reviewer-lane-plan";
+export declare const FRONTIER_SWARM_REVIEWER_LANE_PLAN_VERSION = 1;
+export declare const FRONTIER_SWARM_RUN_STORE_SHARDS_KIND = "frontier.swarm.run-store-shards";
+export declare const FRONTIER_SWARM_RUN_STORE_SHARDS_VERSION = 1;
+export declare const FRONTIER_SWARM_MERGE_ADMISSION_KIND = "frontier.swarm.merge-admission";
+export declare const FRONTIER_SWARM_MERGE_ADMISSION_VERSION = 1;
+export declare const FRONTIER_SWARM_CONTEXT_PACK_KIND = "frontier.swarm.context-pack";
+export declare const FRONTIER_SWARM_CONTEXT_PACK_VERSION = 1;
+export declare const FRONTIER_SWARM_ORACLE_CORPUS_KIND = "frontier.swarm.oracle-corpus";
+export declare const FRONTIER_SWARM_ORACLE_CORPUS_VERSION = 1;
+export declare const FRONTIER_SWARM_LANE_PLAYBOOK_KIND = "frontier.swarm.lane-playbook";
+export declare const FRONTIER_SWARM_LANE_PLAYBOOK_VERSION = 1;
+export declare const FRONTIER_SWARM_PATCH_STACK_PLAN_KIND = "frontier.swarm.patch-stack-plan";
+export declare const FRONTIER_SWARM_PATCH_STACK_PLAN_VERSION = 1;
 export declare const FRONTIER_SWARM_DEFAULT_CODEX_COMPUTE_ID = "codex.gpt-5.5.xhigh";
 export declare const FRONTIER_SWARM_DEFAULT_MODEL = "gpt-5.5";
 export declare const FRONTIER_SWARM_DEFAULT_REASONING_EFFORT = "xhigh";
@@ -42,6 +62,8 @@ export type FrontierSwarmJobStatus = 'planned' | 'scheduled' | 'running' | 'bloc
 export type FrontierSwarmMergeReadiness = 'discovery-only' | 'patch-candidate' | 'verified-patch' | 'rejected' | 'blocked' | string;
 export type FrontierSwarmMergeDisposition = 'auto-mergeable' | 'needs-port' | 'discovery-only' | 'rejected' | 'blocked' | 'stale-against-head' | string;
 export type FrontierSwarmRiskLevel = 'low' | 'medium' | 'high' | 'unknown' | string;
+export type FrontierSwarmPatchStatus = 'unknown' | 'applies' | 'missing' | 'stale' | 'failed-check' | string;
+export type FrontierSwarmQueueOverlayStatus = 'satisfied' | 'ready-to-apply' | 'needs-human-port' | 'failed-evidence' | 'stale-against-head' | 'discovery-only' | 'blocked' | 'rejected' | 'unknown' | string;
 export interface FrontierSwarmComputeInput {
     id: string;
     kind?: FrontierSwarmComputeKind;
@@ -1028,6 +1050,423 @@ export interface FrontierSwarmMergeBundle {
     reasons: string[];
     metadata?: JsonObject;
 }
+export interface FrontierSwarmQueueOverlayInput {
+    id?: string;
+    runId?: string;
+    bundles?: readonly FrontierSwarmMergeBundle[];
+    results?: readonly (FrontierSwarmJobResult | FrontierSwarmJobResultInput)[];
+    generatedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmQueueOverlay {
+    kind: typeof FRONTIER_SWARM_QUEUE_OVERLAY_KIND;
+    version: typeof FRONTIER_SWARM_QUEUE_OVERLAY_VERSION;
+    id: string;
+    runId?: string;
+    generatedAt: number;
+    entries: FrontierSwarmQueueOverlayEntry[];
+    byQueueItemId: Record<string, FrontierSwarmQueueOverlayEntry[]>;
+    summary: {
+        entryCount: number;
+        queueItemCount: number;
+        readyToApplyCount: number;
+        needsHumanPortCount: number;
+        failedEvidenceCount: number;
+        staleAgainstHeadCount: number;
+        discoveryOnlyCount: number;
+    };
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmQueueOverlayEntry {
+    queueItemId: string;
+    jobId: string;
+    status: FrontierSwarmQueueOverlayStatus;
+    mergeReadiness: FrontierSwarmMergeReadiness;
+    disposition: FrontierSwarmMergeDisposition;
+    riskLevel: FrontierSwarmRiskLevel;
+    patchPath?: string;
+    evidencePaths: string[];
+    changedPaths: string[];
+    changedRegions: string[];
+    reasons: string[];
+    generatedAt: number;
+}
+export interface FrontierSwarmDerivedQueueStatusInput {
+    snapshot: FrontierSwarmQueueSnapshot;
+    overlays?: readonly FrontierSwarmQueueOverlay[];
+    generatedAt?: number;
+}
+export interface FrontierSwarmDerivedQueueStatus {
+    generatedAt: number;
+    jobs: FrontierSwarmQueueJob[];
+    byStatus: Record<string, string[]>;
+    summary: FrontierSwarmQueueSnapshot['summary'];
+}
+export interface FrontierSwarmMergeIndexInput {
+    id?: string;
+    runId?: string;
+    planId?: string;
+    bundles: readonly FrontierSwarmMergeBundle[];
+    patchStatuses?: Record<string, FrontierSwarmPatchStatus>;
+    generatedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmMergeIndex {
+    kind: typeof FRONTIER_SWARM_MERGE_INDEX_KIND;
+    version: typeof FRONTIER_SWARM_MERGE_INDEX_VERSION;
+    id: string;
+    runId?: string;
+    planId?: string;
+    generatedAt: number;
+    entries: FrontierSwarmMergeIndexEntry[];
+    conflicts: FrontierSwarmMergeConflict[];
+    byDisposition: Record<string, string[]>;
+    byPath: Record<string, string[]>;
+    byRegion: Record<string, string[]>;
+    summary: {
+        entryCount: number;
+        readyToApplyCount: number;
+        needsHumanPortCount: number;
+        failedEvidenceCount: number;
+        staleAgainstHeadCount: number;
+        discoveryOnlyCount: number;
+        conflictCount: number;
+        conflictedJobCount: number;
+    };
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmMergeIndexEntry {
+    jobId: string;
+    taskId?: string;
+    lane?: string;
+    title?: string;
+    status: FrontierSwarmJobStatus;
+    mergeReadiness: FrontierSwarmMergeReadiness;
+    disposition: FrontierSwarmMergeDisposition;
+    riskLevel: FrontierSwarmRiskLevel;
+    patchStatus: FrontierSwarmPatchStatus;
+    staleAgainstHead: boolean;
+    autoMergeable: boolean;
+    changedPaths: string[];
+    changedRegions: string[];
+    conflictKeys: string[];
+    conflictingJobIds: string[];
+    ownedFilesTouched: string[];
+    ownershipViolations: string[];
+    patchPath?: string;
+    patchHash?: string;
+    evidencePaths: string[];
+    queueItemIds: string[];
+    reasons: string[];
+    generatedAt: number;
+}
+export interface FrontierSwarmMergeConflict {
+    jobIds: string[];
+    key: string;
+    kind: 'path' | 'region';
+    path?: string;
+    region?: string;
+}
+export interface FrontierSwarmRegionOwnershipInput {
+    changedPaths?: readonly string[];
+    changedRegions?: readonly string[];
+}
+export interface FrontierSwarmRegionOwnershipReport {
+    ok: boolean;
+    jobId: string;
+    changedPaths: string[];
+    changedRegions: string[];
+    ownedRegions: string[];
+    regionViolations: string[];
+    unclassifiedChangedPaths: string[];
+}
+export interface FrontierSwarmHotspotReportInput {
+    id?: string;
+    bundles?: readonly FrontierSwarmMergeBundle[];
+    results?: readonly (FrontierSwarmJobResult | FrontierSwarmJobResultInput)[];
+    threshold?: number;
+    generatedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmHotspotReport {
+    kind: typeof FRONTIER_SWARM_HOTSPOT_REPORT_KIND;
+    version: typeof FRONTIER_SWARM_HOTSPOT_REPORT_VERSION;
+    id: string;
+    generatedAt: number;
+    threshold: number;
+    entries: FrontierSwarmHotspotEntry[];
+    recommendations: FrontierSwarmHotspotRecommendation[];
+    summary: {
+        pathCount: number;
+        hotspotCount: number;
+        recommendationCount: number;
+    };
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmHotspotEntry {
+    path: string;
+    touchCount: number;
+    jobIds: string[];
+    regions: string[];
+    dispositions: string[];
+    riskLevels: string[];
+}
+export interface FrontierSwarmHotspotRecommendation {
+    path: string;
+    reason: 'repeated-conflicts' | 'hot-file' | 'region-overlap';
+    suggestedModuleId: string;
+    suggestedOwnershipRegions: string[];
+    jobIds: string[];
+}
+export interface FrontierSwarmReviewerLanePlanInput {
+    id?: string;
+    index: FrontierSwarmMergeIndex;
+    admission?: FrontierSwarmMergeAdmission;
+    reviewerLane?: string;
+    reviewers?: readonly string[];
+    includeAutoMergeable?: boolean;
+    generatedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmReviewerLanePlan {
+    kind: typeof FRONTIER_SWARM_REVIEWER_LANE_PLAN_KIND;
+    version: typeof FRONTIER_SWARM_REVIEWER_LANE_PLAN_VERSION;
+    id: string;
+    mergeIndexId: string;
+    generatedAt: number;
+    reviewerLane: string;
+    assignments: FrontierSwarmReviewerLaneAssignment[];
+    tasks: FrontierSwarmTaskInput[];
+    summary: {
+        assignmentCount: number;
+        taskCount: number;
+    };
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmReviewerLaneAssignment {
+    jobId: string;
+    reviewers: string[];
+    required: boolean;
+    reasons: string[];
+}
+export interface FrontierSwarmRunStoreShardsInput {
+    id?: string;
+    run?: FrontierSwarmRun;
+    plan?: FrontierSwarmPlan;
+    root?: string;
+    shardSize?: number;
+    groupBy?: 'lane' | 'hash' | 'none';
+    generatedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmRunStoreShards {
+    kind: typeof FRONTIER_SWARM_RUN_STORE_SHARDS_KIND;
+    version: typeof FRONTIER_SWARM_RUN_STORE_SHARDS_VERSION;
+    id: string;
+    runId?: string;
+    planId?: string;
+    root: string;
+    generatedAt: number;
+    groupBy: 'lane' | 'hash' | 'none';
+    shardSize: number;
+    shards: FrontierSwarmRunStoreShard[];
+    summary: {
+        shardCount: number;
+        jobCount: number;
+    };
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmRunStoreShard {
+    id: string;
+    lane?: string;
+    path: string;
+    eventPath: string;
+    resultPath: string;
+    checkpointPath: string;
+    jobIds: string[];
+}
+export interface FrontierSwarmMergeAdmissionInput {
+    id?: string;
+    index: FrontierSwarmMergeIndex;
+    maxReady?: number;
+    maxChangedPaths?: number;
+    maxChangedRegions?: number;
+    maxHighRisk?: number;
+    allowRisks?: readonly FrontierSwarmRiskLevel[];
+    generatedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmMergeAdmission {
+    kind: typeof FRONTIER_SWARM_MERGE_ADMISSION_KIND;
+    version: typeof FRONTIER_SWARM_MERGE_ADMISSION_VERSION;
+    id: string;
+    mergeIndexId: string;
+    generatedAt: number;
+    admitted: string[];
+    deferred: FrontierSwarmMergeAdmissionDeferral[];
+    budget: {
+        maxReady: number;
+        maxChangedPaths?: number;
+        maxChangedRegions?: number;
+        maxHighRisk?: number;
+        allowRisks: string[];
+    };
+    summary: {
+        admittedCount: number;
+        deferredCount: number;
+        changedPathCount: number;
+        changedRegionCount: number;
+        highRiskCount: number;
+    };
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmMergeAdmissionDeferral {
+    jobId: string;
+    reasons: string[];
+}
+export interface FrontierSwarmContextPackInput {
+    id?: string;
+    job?: FrontierSwarmJob;
+    task?: FrontierSwarmTask | FrontierSwarmTaskInput;
+    title?: string;
+    files?: readonly string[];
+    apiMap?: Record<string, readonly string[]>;
+    knownFailures?: readonly string[];
+    commands?: readonly (string | FrontierSwarmCommandInput)[];
+    oracleCommands?: readonly (string | FrontierSwarmCommandInput)[];
+    evidenceSchema?: unknown;
+    expectedEvidence?: readonly string[];
+    exclusions?: readonly string[];
+    avoidInvestigating?: readonly string[];
+    playbookIds?: readonly string[];
+    generatedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmContextPack {
+    kind: typeof FRONTIER_SWARM_CONTEXT_PACK_KIND;
+    version: typeof FRONTIER_SWARM_CONTEXT_PACK_VERSION;
+    id: string;
+    jobId?: string;
+    taskId?: string;
+    lane?: string;
+    title: string;
+    generatedAt: number;
+    files: string[];
+    apiMap: Record<string, string[]>;
+    knownFailures: string[];
+    commands: FrontierSwarmCommand[];
+    oracleCommands: FrontierSwarmCommand[];
+    evidenceSchema?: JsonValue;
+    expectedEvidence: string[];
+    exclusions: string[];
+    avoidInvestigating: string[];
+    playbookIds: string[];
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmOracleArtifactInput {
+    id: string;
+    path: string;
+    kind?: string;
+    command?: string | FrontierSwarmCommandInput;
+    hash?: string;
+    sourceRef?: string;
+    tags?: readonly string[];
+    metadata?: unknown;
+}
+export interface FrontierSwarmOracleArtifact {
+    id: string;
+    path: string;
+    kind: string;
+    command?: FrontierSwarmCommand;
+    hash?: string;
+    sourceRef?: string;
+    tags: string[];
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmOracleCorpusInput {
+    id?: string;
+    title?: string;
+    artifacts?: readonly FrontierSwarmOracleArtifactInput[];
+    generatedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmOracleCorpus {
+    kind: typeof FRONTIER_SWARM_ORACLE_CORPUS_KIND;
+    version: typeof FRONTIER_SWARM_ORACLE_CORPUS_VERSION;
+    id: string;
+    title: string;
+    generatedAt: number;
+    artifacts: FrontierSwarmOracleArtifact[];
+    byKind: Record<string, string[]>;
+    byTag: Record<string, string[]>;
+    summary: {
+        artifactCount: number;
+        kindCount: number;
+        tagCount: number;
+    };
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmLanePlaybookInput {
+    id?: string;
+    lane: string;
+    title?: string;
+    successfulBundles?: readonly FrontierSwarmMergeBundle[];
+    notes?: readonly string[];
+    commands?: readonly (string | FrontierSwarmCommandInput)[];
+    avoidInvestigating?: readonly string[];
+    evidencePatterns?: readonly string[];
+    generatedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmLanePlaybook {
+    kind: typeof FRONTIER_SWARM_LANE_PLAYBOOK_KIND;
+    version: typeof FRONTIER_SWARM_LANE_PLAYBOOK_VERSION;
+    id: string;
+    lane: string;
+    title: string;
+    generatedAt: number;
+    notes: string[];
+    commands: FrontierSwarmCommand[];
+    avoidInvestigating: string[];
+    evidencePatterns: string[];
+    successfulJobIds: string[];
+    hotPaths: string[];
+    changedRegions: string[];
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmPatchStackPlanInput {
+    id?: string;
+    index: FrontierSwarmMergeIndex;
+    maxStackSize?: number;
+    generatedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmPatchStackPlan {
+    kind: typeof FRONTIER_SWARM_PATCH_STACK_PLAN_KIND;
+    version: typeof FRONTIER_SWARM_PATCH_STACK_PLAN_VERSION;
+    id: string;
+    mergeIndexId: string;
+    generatedAt: number;
+    stacks: FrontierSwarmPatchStack[];
+    summary: {
+        stackCount: number;
+        jobCount: number;
+        conflictedStackCount: number;
+    };
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmPatchStack {
+    id: string;
+    title: string;
+    lane?: string;
+    jobIds: string[];
+    changedPaths: string[];
+    changedRegions: string[];
+    riskLevels: string[];
+    dispositions: string[];
+    conflicts: FrontierSwarmMergeConflict[];
+    gateHints: string[];
+}
 export interface FrontierSwarmProof {
     kind: typeof FRONTIER_SWARM_PROOF_KIND;
     version: typeof FRONTIER_SWARM_PROOF_VERSION;
@@ -1059,6 +1498,18 @@ export declare function classifySwarmMergeDisposition(result: FrontierSwarmJobRe
     staleAgainstHead?: boolean;
 }): FrontierSwarmMergeDisposition;
 export declare function createSwarmMergeBundle(input: FrontierSwarmMergeBundleInput): FrontierSwarmMergeBundle;
+export declare function createSwarmQueueOverlay(input?: FrontierSwarmQueueOverlayInput): FrontierSwarmQueueOverlay;
+export declare function deriveSwarmQueueStatus(input: FrontierSwarmDerivedQueueStatusInput): FrontierSwarmDerivedQueueStatus;
+export declare function createSwarmMergeIndex(input: FrontierSwarmMergeIndexInput): FrontierSwarmMergeIndex;
+export declare function checkSwarmRegionOwnership(job: FrontierSwarmJob, input?: FrontierSwarmRegionOwnershipInput): FrontierSwarmRegionOwnershipReport;
+export declare function createSwarmHotspotReport(input?: FrontierSwarmHotspotReportInput): FrontierSwarmHotspotReport;
+export declare function createSwarmReviewerLanePlan(input: FrontierSwarmReviewerLanePlanInput): FrontierSwarmReviewerLanePlan;
+export declare function createSwarmRunStoreShards(input?: FrontierSwarmRunStoreShardsInput): FrontierSwarmRunStoreShards;
+export declare function createSwarmMergeAdmission(input: FrontierSwarmMergeAdmissionInput): FrontierSwarmMergeAdmission;
+export declare function createSwarmContextPack(input?: FrontierSwarmContextPackInput): FrontierSwarmContextPack;
+export declare function createSwarmOracleCorpus(input?: FrontierSwarmOracleCorpusInput): FrontierSwarmOracleCorpus;
+export declare function createSwarmLanePlaybook(input: FrontierSwarmLanePlaybookInput): FrontierSwarmLanePlaybook;
+export declare function createSwarmPatchStackPlan(input: FrontierSwarmPatchStackPlanInput): FrontierSwarmPatchStackPlan;
 export declare function resolveSwarmCompute(manifestInput: FrontierSwarmManifest | FrontierSwarmManifestInput, taskInput: FrontierSwarmTask | FrontierSwarmTaskInput): FrontierSwarmCompute;
 export declare function createSwarmProof(input: FrontierSwarmManifest | FrontierSwarmPlan | FrontierSwarmRun, options?: {
     generatedAt?: number;