@shapeshift-labs/frontier-swarm 0.5.20 → 0.5.22

package/README.md

@@ -2,7 +2,81 @@
 
 Hierarchical swarm plans, lanes, compute profiles, ownership policy, events, and proofs for Frontier agent work.
 
-`frontier-swarm` turns parallel agent work into data: manifests, parent/child swarm layers, compute profiles, lane ownership, task queues, dry-run plans, event streams, changed-path checks, job results, and proof hashes. It does not spawn processes, create git worktrees, call Codex, or talk to queue brokers. Runners attach through structural adapters such as `@shapeshift-labs/frontier-swarm-codex`.
+`frontier-swarm` turns parallel agent work into data: manifests, parent/child swarm layers, compute profiles, model-route recommendations, lane ownership, task queues, dry-run plans, event streams, changed-path checks, job results, and proof hashes. It does not spawn processes, create git worktrees, call Codex, or talk to queue brokers. Runners attach through structural adapters such as `@shapeshift-labs/frontier-swarm-codex`.
+
+Verification gate metadata stays plain JSON. `mergeSwarmMetadata(...)` preserves `metadata.verificationGates` across task normalization, queue jobs, merge bundles, merge indexes, and coordinator drain assignments, and package-scoped gate descriptors can carry `metadata.packageId`, `metadata.packagePath`, and `metadata.packageName` without pulling in Codex-specific runtime code.
+
+## Package Contract Skew 08
+
+Keep aggregate package changes and standalone main remotes on the same catalog snapshot. The safe publish-main sequence is:
+
+1. land the aggregate package change first,
+2. regenerate the package-family README content from the shared catalog instead of copying older monolithic or split-package prose,
+3. run the package-local gate for the changed surface,
+4. push the standalone `main` remote only after the generated docs and the package gate agree with the aggregate branch,
+5. if a standalone remote still shows stale package-layout wording, refresh it from the catalog-backed source rather than preserving the drift.
+
+This prevents later publish-only patches from reintroducing stale monolithic/split package drift.
+
+## Semantic Ownership Keys
+
+Semantic ownership regions use stable, repo-agnostic key prefixes. The package exports the canonical prefixes as `FRONTIER_SWARM_SEMANTIC_OWNERSHIP_KEYS` and also exposes `createSwarmSemanticOwnershipKey(...)` for composing region selectors.
+
+- `export` for exported symbols,
+- `type` for type declarations,
+- `cli-command` for CLI command surfaces,
+- `docs-section` for documentation headings,
+- `fixture-family` for fixture groups,
+- `test-case` for test case ownership.
+
+Backlog-oriented adapters can use `createSwarmBacklog(...)`, `mergeSwarmBacklogs(...)`, `querySwarmBacklog(...)`, and `createSwarmBacklogTaskPlan(...)` to normalize backlog entries, fold multiple backlog snapshots together, and derive runnable plus recursive decomposition task plans for continuation workflows.
+
+## Priority Scheduling
+
+Plans, schedules, and queue snapshots include `metadata.priorityPolicy` using the exported `FRONTIER_SWARM_REVIEW_PRIORITY_POLICY`. The policy puts coordinator-drain and review work in the top priority band, keeps speculative backlog in a lower band, and round-robins lanes inside each band before falling back to the task's numeric `priority`. Lane limits, compute limits, resource quotas, and `concurrencyKey` limits still gate readiness; the priority policy only changes candidate order.
+
+## Continuous Pool State
+
+`createSwarmContinuousPoolState()` models a runtime-neutral autonomous worker pool from active leases, queue snapshots, schedules, coordinator drain work, queue outcome decisions, and explicit work-item buckets. It reports active, queued, review-drain, rerun, human-blocked, conflicted, capacity-blocked, and done buckets, then derives refill slots and stop conditions from those buckets.
+
+Refill recommendations fill idle capacity with coordinator drain and rerun work before queued implementation work, and speculative backlog is selected after standard queued work. A pool is only marked `drained` when active, queued, review-drain, rerun, human-blocked, conflicted, and capacity-blocked buckets are all empty. Remaining human-question, conflict, or capacity blockers produce explicit `human-blocked`, `conflicted`, or `capacity-blocked` stop conditions instead of being collapsed into done output.
+
+## Hierarchical Merge Queues
+
+`createSwarmHierarchicalMergeQueue()` turns a merge index plus optional admission budget into root, parent, child, lane, semantic-region, and path queues. Clean admitted work can be applied by the local queue, clean excess work stays queued locally, stale work is marked for rerun, failed evidence is rejected, discovery work is tracked as record-only but normalizes to no-change, true blockers stay blocked, and cross-scope or public-contract work is promoted upward. Same-scope conflicts stay local unless they need a broader decision. High-risk work stays local unless admission explicitly allows it.
+
+Clean auto-mergeable work that spans multiple known semantic regions is returned as a `rerun` assignment with `retrySlices`, `semanticSliceScopeIds`, and `semanticSliceLeaseKeys`. Each retry slice carries its own required lease scope/key so runners can produce independently reviewable same-file slice bundles. If admission has already accepted a still-unsliced cross-scope patch, the `apply-local` assignment remains atomic and carries all `semanticSliceScopeIds` and `semanticSliceLeaseKeys` so runners can acquire every required semantic lease before applying it once. Same-region conflicts still serialize under one local lease, while unknown regions, public-contract regions, and parent-scope regions promote to the parent queue for a broader decision.
+
+Queue and coordinator-drain assignments also expose `requiredLeaseScopeIds` and `requiredLeaseKeys`. For independent same-file semantic regions these required leases stay at the semantic-region level, allowing multiple coordinators to acquire different locks for the same changed file. For promoted work, including shared parent-scope edits, the required lease is the promotion target such as the lane or root queue, so conflicting changes serialize under a parent decision without relying on package-specific names. Root lease keys are always derived from the caller-supplied `rootScopeId`, so the default root scope uses `merge:root:root` and custom roots get matching queue-local keys.
+
+Root lease keys are derived from the caller-supplied `rootScopeId`, so the queue model does not special-case any literal root identifier.
+
+The queue model is generic. Runners can map scopes to any repository, package, feature, service, file, symbol, or semantic ownership region without baking project-specific package names into the core package.
+
+`createSwarmSemanticOwnershipStableKey` and `createSwarmSemanticOwnershipRegionId` keep export, type, CLI command, docs section, fixture family, and test case ownership keys stable across discovery order and queue replay.
+The canonical stable-key prefixes are `exported-declaration`, `type-declaration`, `cli-command`, `docs-section`, `fixture-family`, and `test-case`.
+The generic `export` alias resolves to `exported-declaration`, so named, default, and explicit export ownership share one stable key family.
+The exported `FRONTIER_SWARM_SEMANTIC_OWNERSHIP_STABLE_KEY_KINDS` table exposes those canonical labels under stable names for downstream adapters.
+
+Caller-provided `scopes` are serialized as opaque queue scopes. Their `id`, `kind`, `leaseKey`, `changedPaths`, `changedRegions`, and `metadata` stay runner-owned, with `kind` defaulting to `custom`; callers can model root, parent, child, lane, semantic-region, and path scopes without changing the core queue logic.
+
+`createSwarmHierarchicalMergeQueue()` also exposes a generic `scopeTree` summary with `scopeIdsByKind`, `ancestorScopeIdsByScopeId`, `childScopeIdsByScopeId`, and `leafScopeIds`. The tree is derived from the declared scope kinds and `parentId` links, so adapters can inspect root, parent, child, lane, semantic-region, and path scopes without assuming any Frontier-specific package, repo, or feature naming scheme.
+
+Hierarchical queues also emit `leaseRecords` for root, parent, child, lane, semantic-region, path, and custom scopes. These records are generic agent merge-queue infrastructure: they carry the lease key, optional local leader metadata, active and terminal queue item IDs, conflict and retry reasons, parent-promotion state, and terminal decision links back to the queue items they close. Adapters can use those records to let independent semantic scopes make progress concurrently while same-scope work serializes under one lease.
+
+Queue-local conflict decisions stay in the `continuation` bucket, so routine conflicts that are already contained within one scope do not get mislabeled as human review debt.
+
+This keeps the root coordinator from becoming the only place where work can make progress. A child queue can apply verified work under its own lease, leave clean overflow in `queue-local`, and promote only the items that need a parent decision. Adapters such as `@shapeshift-labs/frontier-swarm-codex` can layer run, collect, Loom, auto-drain, rerun, reject, discovery, and blocker workflows on top of the generic queue data.
+
+`createSwarmQueueOutcomeModel()` and `collapseSwarmQueueOutcomeDecisions()` provide a repo-agnostic outcome layer for autonomous merge queues. The model separates `terminal`, `continuation`, `coordinator-review`, `human-blocked`, `stale-rerun`, and `conflict` categories so "needs coordinator review" does not get reported as a true human blocker. Queue subjects are collapsed across `queueItemIds`, `taskId`, and `jobId` aliases, and only the latest decision for each subject contributes to visible review debt, blockers, reruns, and conflicts. This lets a newer committed/applied/checked/rejected decision close old review or rerun records without requiring runners to mutate historical queue files.
+
+Queue decisions that resolve to conflict, stale rerun, checked completion, or human review normalize to explicit `conflict-blocked`, `rerun`, `checked`, and `human-question` terminal labels, while record-only and closed outcomes collapse to `no-change`, so queue items always have a concrete terminal outcome instead of falling through to an ambiguous internal state.
+
+`normalizeSwarmTerminalOutcome()` keeps terminal labels explicit and stable across bundle, collector, and queue surfaces. It normalizes `applied`, `committed`, `checked`, `superseded`, `evidence-only`, `no-change`, and `generated-by-collector` as success states; `patch-missing` and `bundle-missing` as incomplete result states; and `rerun`, `rejected`, `conflict-blocked`, `human-question`, and `coordinator-review` as distinct terminal outcomes for downstream routing. `human-blocked` remains accepted as a legacy alias, while `coordinator-review` stays review-only and does not count as a human blocker.
+
+`createSwarmTerminalOutcomeRecord()` exports a repository-generic final admission record for runners and coordinators. Its canonical statuses are `applied`, `rejected`, `superseded`, `no-change`, `conflict`, `human-needed`, `research-complete`, and `rerun`; reason codes are similarly generic (`accepted-by-admission`, `failed-verification`, `superseded-by-newer-output`, `no-effective-change`, `conflict-detected`, `human-decision-required`, `research-complete`, and `stale-rerun-required`). The record carries queue/task/job aliases, evidence refs, conflict peers, rerun and supersession links, and boolean routing flags without assuming Codex, git, package, or repository-specific fields.
+
+`reconcileSwarmTerminalState()` adapts older runner bucket snapshots such as `ready`, `review`, `stale`, and `failed` to the newer autonomous decision ledger. A later committed, applied, superseded, or no-change decision for the same queue item, task, or job moves the subject into resolved `done` output instead of leaving it in review debt. Rejected, rerun, conflict-blocked, and human-question decisions remain visible in terminal output, and `human-blocked` stays as a compatibility alias, but they are not counted as ordinary failed worker results.
 
 
 ## Related Packages
@@ -22,6 +96,7 @@ The published Frontier package family is generated from one shared package catal
 - [`@shapeshift-labs/frontier-schema`](https://www.npmjs.com/package/@shapeshift-labs/frontier-schema): JSON Schema validation, Frontier profile generation, CloudEvent envelopes, and query/table schema helpers.
 - [`@shapeshift-labs/frontier-migrations`](https://www.npmjs.com/package/@shapeshift-labs/frontier-migrations): Boundary-first data migrations, import normalization, plugin/API version mapping, versioned envelopes, graph diagnostics, patch path rewrites, dry-run reports, and current-shape rehydration.
 - [`@shapeshift-labs/frontier-event-log`](https://www.npmjs.com/package/@shapeshift-labs/frontier-event-log): Bounded event logs, replay cursors, consumer acknowledgements, keyed compaction, checkpoints, and Frontier patch event records.
+- [`@shapeshift-labs/frontier-run`](https://www.npmjs.com/package/@shapeshift-labs/frontier-run): Append-only distributed run graphs, causal event DAGs, evidence nodes, lanes, leases, refs, segments, dashboard projections, and admission decision records for Frontier agent work.
 - [`@shapeshift-labs/frontier-inspect`](https://www.npmjs.com/package/@shapeshift-labs/frontier-inspect): Cross-package inspection/evidence bundles, registry graph snapshots, feature/resource impact reports, timeline/event normalization, redaction, JSONL import/export, and AI-readable app feature maps.
 - [`@shapeshift-labs/frontier-scheduler`](https://www.npmjs.com/package/@shapeshift-labs/frontier-scheduler): Deterministic work scheduling, lanes, cancellation, backpressure, frame policies, replay snapshots, and work graphs.
 - [`@shapeshift-labs/frontier-logging`](https://www.npmjs.com/package/@shapeshift-labs/frontier-logging): Opt-in structured logging, browser telemetry, scheduled sinks, file sinks, exporters, benchmark traces, and Frontier patch/update summaries.
@@ -52,7 +127,7 @@ The published Frontier package family is generated from one shared package catal
 - [`@shapeshift-labs/frontier-lang-go`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang-go): Go source-language importer package for Frontier Lang semantic documents, including package-level metadata, Go AST adapter helpers, native import results, and semantic sidecar generation for go/ast File or Package trees.
 - [`@shapeshift-labs/frontier-lang-csharp`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang-csharp): C# Roslyn source-language importer package for Frontier Lang semantic documents, including package-level metadata, Roslyn adapter helpers, native import results, and semantic sidecar generation for SyntaxTree/SyntaxNode-shaped ASTs.
 - [`@shapeshift-labs/frontier-lang-clang`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang-clang): Clang AST source-language importer package for Frontier Lang semantic documents, including package-level metadata, Clang AST JSON adapter helpers, native import results, and semantic sidecar generation for C/C++ translation units.
-- [`@shapeshift-labs/frontier-lang-cli`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang-cli): Command line interface for parsing, checking, hashing, and emitting Frontier Lang projects.
+- [`@shapeshift-labs/frontier-lang-cli`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang-cli): Command line interface for parsing, checking, hashing, emitting, native source import/projection, semantic slicing, and corpus roundtrip evidence for Frontier Lang projects.
 - [`@shapeshift-labs/frontier-lang`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang): Umbrella package for Frontier Lang kernel, parser, checker, compiler facade, universal AST helpers, projection adapters, and source-language importer adapters.
 - [`@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.
@@ -98,6 +173,7 @@ The published Frontier package family is generated from one shared package catal
 - [`@shapeshift-labs/frontier-realtime-server`](https://www.npmjs.com/package/@shapeshift-labs/frontier-realtime-server): Authoritative realtime room, tick, command validation, rate-limit, session, and snapshot-history runtime.
 - [`@shapeshift-labs/frontier-realtime-websocket`](https://www.npmjs.com/package/@shapeshift-labs/frontier-realtime-websocket): WebSocket client, wire, and Node room-server transport for Frontier realtime.
 - [`@shapeshift-labs/frontier-game`](https://www.npmjs.com/package/@shapeshift-labs/frontier-game): Game-facing entity, component, player, room, ownership, spatial interest, rollback, physics, and replication helpers above realtime.
+- [`@shapeshift-labs/loom`](https://www.npmjs.com/package/@shapeshift-labs/loom): Repo-level semantic collaboration CLI for .loom workspaces, including init, scan, status, graph snapshots, projection plans, Frontier Lang delegation, Frontier Swarm delegation, and Frontier Framework delegation.
 
 Package source repositories:
 
@@ -114,6 +190,7 @@ Package source repositories:
 - [`siliconjungle/-shapeshift-labs-frontier-schema`](https://github.com/siliconjungle/-shapeshift-labs-frontier-schema)
 - [`siliconjungle/-shapeshift-labs-frontier-migrations`](https://github.com/siliconjungle/-shapeshift-labs-frontier-migrations)
 - [`siliconjungle/-shapeshift-labs-frontier-event-log`](https://github.com/siliconjungle/-shapeshift-labs-frontier-event-log)
+- [`siliconjungle/-shapeshift-labs-frontier-run`](https://github.com/siliconjungle/-shapeshift-labs-frontier-run)
 - [`siliconjungle/-shapeshift-labs-frontier-inspect`](https://github.com/siliconjungle/-shapeshift-labs-frontier-inspect)
 - [`siliconjungle/-shapeshift-labs-frontier-scheduler`](https://github.com/siliconjungle/-shapeshift-labs-frontier-scheduler)
 - [`siliconjungle/-shapeshift-labs-frontier-logging`](https://github.com/siliconjungle/-shapeshift-labs-frontier-logging)
@@ -191,6 +268,7 @@ Package source repositories:
 - [`siliconjungle/-shapeshift-labs-frontier-realtime-server`](https://github.com/siliconjungle/-shapeshift-labs-frontier-realtime-server)
 - [`siliconjungle/-shapeshift-labs-frontier-realtime-websocket`](https://github.com/siliconjungle/-shapeshift-labs-frontier-realtime-websocket)
 - [`siliconjungle/-shapeshift-labs-frontier-game`](https://github.com/siliconjungle/-shapeshift-labs-frontier-game)
+- [`siliconjungle/-shapeshift-labs-loom`](https://github.com/siliconjungle/-shapeshift-labs-loom)
 
 ## Install
 
@@ -237,70 +315,6 @@ const tasks = defineSwarmTasks([{
 const plan = createSwarmPlan(manifest, tasks, { limit: 4 });
 ```
 
-## Strategy Tournaments
-
-Use strategy tournaments when several workers, merge policies, proof searches, or projection routes need to be compared by more than raw completion status. The records are runtime-neutral JSON: discovery/search cost is separate from the verification certificate, undefined outcomes stay explicit, and standings are deterministic.
-
-```ts
-import {
-  createSwarmPayoffVector,
-  createSwarmStrategyTournament,
-  createSwarmStrategyTournamentHistory,
-  compareSwarmStrategyTournaments,
-  createSwarmTournamentAdaptiveFeedback,
-  createSwarmAdaptiveLoadPlan
-} from '@shapeshift-labs/frontier-swarm';
-
-const tournament = createSwarmStrategyTournament({
-  strategies: [
-    { id: 'trace-first', family: 'oracle-search' },
-    { id: 'patch-first', family: 'implementation' }
-  ],
-  games: [
-    { id: 'merge-admission', objective: 'prefer replayable verified patches' }
-  ],
-  matches: [{
-    payoff: createSwarmPayoffVector({
-      strategyId: 'trace-first',
-      gameId: 'merge-admission',
-      outcome: 'verified',
-      components: {
-        correctness: 1,
-        evidence: 0.9,
-        reviewCost: { value: 0.2, direction: 'minimize', weight: 0.5 }
-      },
-      search: { attempts: 8, durationMs: 12000, tokens: 24000 },
-      certificate: { commands: ['npm test'], durationMs: 1500 }
-    })
-  }]
-});
-
-const history = createSwarmStrategyTournamentHistory({
-  tournaments: [tournament]
-});
-
-const comparison = compareSwarmStrategyTournaments({
-  baseline: tournament,
-  current: tournament,
-  scoreThreshold: 5
-});
-
-const feedback = createSwarmTournamentAdaptiveFeedback({
-  tournament,
-  history,
-  comparison,
-  scoreFloor: 40
-});
-
-const adaptive = createSwarmAdaptiveLoadPlan({
-  mode: 'balanced',
-  tournamentFeedback: feedback,
-  maxLimits: { maxReadyJobs: 8 }
-});
-```
-
-`history` tracks strategy performance across runs, `comparison` highlights regressions and improvements between two tournaments, and `feedback` can be passed into `createSwarmAdaptiveLoadPlan` as replayable observations. Feedback maps landed/verified outcomes to healthy throughput and noisy, stale, regressed, or discovery-only outcomes to deterministic reduction signals; when strategy or match metadata includes `lane` or `concurrencyKey`, the adaptive planner can adjust those specific scheduler limits without reading mutable tournament state. This makes prompt styles, workspace modes, evidence requirements, and merge policies comparable as strategies instead of treating every worker bundle as a one-off result.
-
 ## 1000-Agent Control Plane
 
 Large swarms need a control plane, not just a flat worker loop. `frontier-swarm` now exports deterministic data helpers for that layer:
@@ -346,87 +360,29 @@ 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`,
-- job results, merge bundles, queue overlays, and merge indexes can carry `semanticImport` summaries for imported symbols, semantic dependency relations, semantic ownership regions, proof/spec obligations, paradigm semantics/lowering records, source projection/native compile readiness, and empty sidecar detection,
 - `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,
+- `createSwarmMergeBundle` builds a compact worker `merge.json` shape with touched owned files, patch path, evidence, verification command metadata (`name`, `command`, `commandLine`, `cwd`, `status`, `required`, `durationMs`, and category hints), queue items satisfied, risk, and disposition, and keeps evidence-only bundles distinct from bundles that actually contain passing checks,
 - `createSwarmQueueOverlay` and `deriveSwarmQueueStatus` keep central queue files immutable while deriving status from worker result overlays,
+- `mergeSwarmMetadata` keeps task and queue metadata data-only while carrying verification gate descriptors forward through queue, bundle, and drain transformations,
 - `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,
-- `createSwarmCoordinatorDashboard` and `querySwarmCoordinatorDashboard` combine merge index entries, queue overlays, evidence indexes, admission decisions, duplicate groups, semantic sidecar/dependency summaries, source citations, and worker liveness into one coordinator-query surface with a compact merge score per job,
-- `createSwarmAdaptiveLoadPlan` treats declared concurrency/resource values as maximums and derives lower effective caps from deterministic observations such as browser/resource contention, stale patches, merge conflicts, empty semantic sidecars, log noise, discovery-only overproduction, failed evidence, and healthy throughput,
 - `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,
 - `createSwarmReplayBundle`, `createSwarmParityOracle`, `createSwarmDivergenceReport`, `createSwarmObservabilityPoint`, `createSwarmWatchpointPlan`, and `createSwarmDebugHandoff` model the trace-to-debug workflow: replay finds the narrow window, watchpoints/debug handoff explain the state at that point,
-- `createSwarmTraceShard`, `createSwarmTraceIndex`, and `querySwarmTraceIndex` turn worker trace findings into sortable evidence: row windows, source hypotheses, executable ownership regions, focused tests, reference evidence, and unresolved divergence signals,
 - `createSwarmReferenceOraclePlan` and `createSwarmReferenceOracleResponse` describe reusable reference services for ports, migrations, parity checks, and cross-implementation comparisons,
 - `createSwarmInstrumentationBudget`, `checkSwarmInstrumentationBudget`, and `createSwarmBottleneckReport` keep traces/logs useful without making instrumentation the bottleneck,
 - `createSwarmEvidenceIndex` / `querySwarmEvidenceIndex` and `createSwarmBlackboard` / `querySwarmBlackboard` provide storage-neutral status surfaces for coordinator dashboards, accepted facts, known divergences, rejected theories, and active ownership,
 - `createSwarmArtifactRoutingPlan`, `createSwarmSchedulerRecommendations`, `createSwarmFixtureCatalog`, `createSwarmProgressModel`, `createSwarmAutoReviewReport`, `createSwarmRebaseReport`, and `createSwarmUsageGovernor` cover the merge/review/scheduling tools needed to scale from feature swarms to larger migration and porting swarms,
+- `createSwarmModelRoute` and `createSwarmPanelEvaluation` score runtime-neutral compute candidates from task metadata, model price catalogs, token mix, budget caps, time pressure, and outcome history, then explain single-cheap, single-deep, panel, or tournament routes,
+- `createSwarmOptimizationSummary` keeps routing, panel, fusion, tournament, RSI-style feedback, model diversity, and consumed-feedback telemetry in a storage-neutral summary that distinguishes unavailable telemetry from real zero counts,
 - `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.
 
-## Trace Shards
-
-Trace shards are the generic form of “the worker found the narrow window.” They are not emulator-specific: a row window can be CPU cycles, log rows, replay steps, API events, migration records, or UI interaction frames. The important part is that the shard connects evidence to source hypotheses and executable ownership regions.
-
-```ts
-import {
-  createSwarmCoordinatorDashboard,
-  createSwarmMergeBundle,
-  createSwarmTraceIndex,
-  createSwarmTraceShard,
-  querySwarmTraceIndex
-} from '@shapeshift-labs/frontier-swarm';
-
-const traceShard = createSwarmTraceShard({
-  jobId: 'runtime-worker-12',
-  lane: 'runtime',
-  subject: 'parser-port',
-  rowWindows: [{ start: 6240, end: 6250, firstDivergenceAt: 6243, deltaFields: ['result.value'] }],
-  hypotheses: [{
-    sourcePath: 'src/parser.ts',
-    symbol: 'parseExpression',
-    region: 'parser.expression',
-    confidence: 'high',
-    reason: 'reference trace diverges immediately after expression precedence handling'
-  }],
-  executableOwnershipRegions: [{
-    id: 'parser.expression',
-    sourcePath: 'src/parser.ts',
-    symbol: 'parseExpression',
-    affectedTests: ['npm run test:parser -- --case precedence'],
-    conflictingAssumptions: ['operators are parsed left-to-right']
-  }],
-  focusedTests: ['npm run test:parser -- --case precedence'],
-  referenceEvidence: [{ path: 'agent-runs/runtime-worker-12/reference-trace.jsonl', kind: 'trace' }]
-});
-
-const bundle = createSwarmMergeBundle({
-  result: {
-    jobId: 'runtime-worker-12',
-    status: 'verified',
-    changedPaths: ['src/parser.ts'],
-    changedRegions: ['parser.expression'],
-    verification: [{ status: 0 }]
-  },
-  patchPath: 'agent-runs/runtime-worker-12/changes.patch',
-  traceShards: [traceShard]
-});
-
-const traceIndex = createSwarmTraceIndex({ bundles: [bundle] });
-const expressionFindings = querySwarmTraceIndex(traceIndex, { region: 'parser.expression', minConfidence: 0.9 });
-
-const dashboard = createSwarmCoordinatorDashboard({ bundles: [bundle] });
-const traceReadyJobs = dashboard.jobs.filter((job) => job.traceSummary?.shardCount);
-```
-
-Merge scoring uses trace shards as review evidence, not automatic correctness. Focused tests, reference evidence, and executable regions raise confidence; unresolved divergences and conflicting assumptions lower the score until a coordinator or review worker resolves them.
-
 ## Hierarchical Compute
 
 Higher swarm layers can choose compute for lower layers without binding the core package to Codex or any other runtime. Compute resolution is deterministic:
@@ -439,6 +395,38 @@ Higher swarm layers can choose compute for lower layers without binding the core
 
 That lets a parent swarm route implementation jobs to a deep model while evidence or inspection jobs use a faster profile.
 
+## Model Routing
+
+`createSwarmModelRoute` scores compute candidates directly, and `createSwarmPlan(..., { routingMode, routingPolicy })` can consume matching policy feedback when selecting job compute. Explicit `options.compute` still wins, `routingMode: 'observe'` records a route without changing compute, and `routingMode: 'fill'` only changes compute when matching feedback or policy preferences exist. That lets runners choose the cheapest capable profile by default and escalate or avoid models when task risk, uncertainty, impact, outcome history, budget, cost feedback, or latency pressure justify it.
+
+```ts
+import { createSwarmModelRoute } from '@shapeshift-labs/frontier-swarm';
+
+const route = createSwarmModelRoute({
+  manifest,
+  task: {
+    id: 'routing-policy-change',
+    lane: 'runtime',
+    targetRefs: ['src/router.ts'],
+    metadata: { risk: 'high', uncertainty: 'unknown', impact: 'high' }
+  },
+  tokenEstimate: { inputTokens: 10000, cachedInputTokens: 2000, outputTokens: 2000 },
+  priceCatalog: {
+    fast: { compute: 'fast', inputUsdPerUnit: 0.2, cachedInputUsdPerUnit: 0.02, outputUsdPerUnit: 1, unitTokens: 1000000 },
+    deep: { compute: 'deep', inputUsdPerUnit: 5, cachedInputUsdPerUnit: 0.5, outputUsdPerUnit: 30, unitTokens: 1000000 }
+  },
+  panel: { enabled: true, minRiskScore: 0.7, maxMembers: 2, fuserComputeId: 'deep' }
+});
+```
+
+`FRONTIER_SWARM_TASK_MODEL_PROFILES` records the default task-kind profile catalog, and `resolveSwarmTaskModelProfile(task)` chooses the profile from `task.workKind`. Each profile captures the expected model tier, cost band, context shape, strengths, and known failure modes for that kind of task. The built-in catalog is model-agnostic: callers can supply their own profile models or compute catalog, and `createSwarmModelRoute` keeps the selected compute separate from the task-kind hint. The route scorer then combines task kind, risk, observed history, token price, and latency so implementation/review/oracle work stays on cheaper candidates unless the history says the cheap route is failing, while public API and other high-risk merge work can still escalate.
+
+`createSwarmModelRoutingFeedback` and `createSwarmModelRoutingPolicy` cover the serializable feedback/policy layer above the model router. Matching feedback is converted into model outcome history, cost/duration signals are folded into candidate scoring, prefer/avoid/override signals can select or suppress candidates, and each routed job gets compact `metadata.modelRoute` evidence with fallback, selected, recommended compute ids, policy match counts, cost-signal counts, and route reasons.
+
+`createSwarmOptimizationSummary` gives runners a generic evidence record for routing decisions, panel/fusion decisions, tournament observations, RSI-style routing feedback, model diversity, and whether any feedback was consumed. Telemetry can be omitted entirely when unavailable or emitted with real zero counts when the run observed nothing.
+
+The returned record includes scored candidates, estimated cost and latency, price/outcome telemetry fallbacks, panel confidence lift, residual risk, and a human-readable explanation for `single-cheap`, `single-deep`, `panel`, or `tournament` recommendations.
+
 ## Surface
 
 - `defineSwarmManifest`, `createSwarmManifest`
@@ -448,7 +436,8 @@ That lets a parent swarm route implementation jobs to a deep model while evidenc
 - `createSwarmPlan`, `createSwarmRun`
 - `createSwarmSchedule`, `createSwarmLeases`
 - `createSwarmQueueSnapshot`, `createSwarmRunCheckpoint`
-- `createSwarmQueueOverlay`, `deriveSwarmQueueStatus`
+- `FRONTIER_SWARM_REVIEW_PRIORITY_POLICY`
+- `createSwarmQueueOverlay`, `normalizeSwarmTerminalOutcome`, `createSwarmTerminalOutcomeRecord`, `deriveSwarmQueueStatus`
 - `createSwarmEventStream`, `createSwarmMailbox`, `routeSwarmEventToMailboxes`
 - `checkSwarmBudget`
 - `createSwarmArtifactIndex`
@@ -459,15 +448,17 @@ That lets a parent swarm route implementation jobs to a deep model while evidenc
 - `createSwarmPatchStackPlan`
 - `createSwarmContextPack`, `createSwarmOracleCorpus`, `createSwarmLanePlaybook`
 - `createSwarmReplayBundle`, `createSwarmParityOracle`, `createSwarmDivergenceReport`, `createSwarmObservabilityPoint`
-- `createSwarmTraceShard`, `createSwarmTraceIndex`, `querySwarmTraceIndex`
 - `createSwarmWatchpointPlan`, `createSwarmDebugHandoff`
 - `createSwarmReferenceOraclePlan`, `createSwarmReferenceOracleResponse`
 - `createSwarmInstrumentationBudget`, `checkSwarmInstrumentationBudget`, `createSwarmBottleneckReport`
 - `createSwarmEvidenceIndex`, `querySwarmEvidenceIndex`, `createSwarmBlackboard`, `querySwarmBlackboard`
 - `createSwarmArtifactRoutingPlan`, `createSwarmSchedulerRecommendations`
+- `createSwarmOptimizationSummary`
 - `createSwarmFixtureCatalog`, `createSwarmProgressModel`, `createSwarmAutoReviewReport`, `createSwarmRebaseReport`
 - `createSwarmUsageGovernor`, `checkSwarmUsageGovernor`
-- `createSwarmAdaptiveLoadPlan`, `createSwarmScheduleInputFromAdaptiveLoadPlan`
+- `createSwarmModelRoutingFeedback`, `createSwarmModelRoutingPolicy`
+- `createSwarmModelRoute`, `createSwarmPanelEvaluation`
+- `createSwarmSemanticOwnershipStableKey`, `createSwarmSemanticOwnershipRegionId`
 - `classifySwarmMergeReadiness`, `classifySwarmMergeDisposition`
 - `resolveSwarmChangedRegions`, `checkSwarmRegionOwnership`
 - `decomposeSwarmFeature`
@@ -485,7 +476,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, adaptive load planning, queue snapshots, queue overlays, merge bundles, merge indexes, merge admission, hotspot reports, context packs, oracle corpora, replay/debug/evidence helper creation, trace index/query creation, lane playbooks, patch stack plans, 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, replay/debug/evidence helper creation, lane playbooks, patch stack plans, event routing, run checkpoints, JSONL, and proof hashing.
 
 ## Source Repository