@shapeshift-labs/frontier-swarm 0.5.9 → 0.5.11

package/README.md

@@ -45,7 +45,7 @@ The published Frontier package family is generated from one shared package catal
 - [`@shapeshift-labs/frontier-lang-rust`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang-rust): Rust projection adapter for Frontier Lang semantic documents, including structs, aliases, and action stubs.
 - [`@shapeshift-labs/frontier-lang-python`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang-python): Python projection adapter for Frontier Lang semantic documents, including dataclasses, typed patch records, and action stubs.
 - [`@shapeshift-labs/frontier-lang-c`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang-c): C header projection adapter for Frontier Lang semantic documents, including structs and action prototypes.
-- [`@shapeshift-labs/frontier-lang-compiler`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang-compiler): Compiler facade for Frontier Lang source documents, including parse, check, hash, diagnostics, projection to TypeScript, JavaScript, Rust, Python, and C, and native source-import adapters for semantic merge evidence.
+- [`@shapeshift-labs/frontier-lang-compiler`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang-compiler): Compiler facade for Frontier Lang source documents, including parse, check, hash, diagnostics, universal AST envelopes, proof/paradigm semantic summaries, projection to TypeScript, JavaScript, Rust, Python, and C, and native source-import adapters for semantic merge evidence.
 - [`@shapeshift-labs/frontier-lang-swift`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang-swift): Swift source-language importer package for Frontier Lang semantic documents, including package-level metadata, SwiftSyntax adapter helpers, native import results, and semantic sidecar generation for SwiftSyntax/SwiftParser-shaped syntax trees.
 - [`@shapeshift-labs/frontier-lang-kotlin`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang-kotlin): Kotlin PSI source-language importer package for Frontier Lang semantic documents, including package-level metadata, Kotlin PSI adapter helpers, native import results, and semantic sidecar generation for Kotlin PSI/KtFile-shaped syntax trees.
 - [`@shapeshift-labs/frontier-lang-java`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang-java): Java source-language importer package for Frontier Lang semantic documents, including package-level metadata, Java AST adapter helpers, native import results, and semantic sidecar generation for javac/JDT/JavaParser-shaped ASTs.
@@ -53,7 +53,7 @@ The published Frontier package family is generated from one shared package catal
 - [`@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`](https://www.npmjs.com/package/@shapeshift-labs/frontier-lang): Umbrella package for Frontier Lang kernel, parser, checker, and projection adapters.
+- [`@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, and projection 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.
 - [`@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.
@@ -298,6 +298,7 @@ The scale APIs are runtime-neutral and serializable:
 - `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,
@@ -305,6 +306,63 @@ The scale APIs are runtime-neutral and serializable:
 - `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:
@@ -337,6 +395,7 @@ 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`
@@ -362,7 +421,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, 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, 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.
 
 ## Source Repository
 

package/benchmarks/package-bench-fixtures.mjs

@@ -0,0 +1,95 @@
+import {
+  createSwarmMergeBundle,
+  createSwarmTraceShard
+} from '../dist/index.js';
+
+export function makeBenchManifest() {
+  return {
+    compute: [
+      { id: 'deep', kind: 'codex', model: 'gpt-5.5', reasoningEffort: 'xhigh' },
+      { id: 'fast', kind: 'codex', model: 'gpt-5.4-mini', reasoningEffort: 'medium' }
+    ],
+    layers: [
+      { id: 'parent', childCompute: { implementation: 'deep', evidence: 'fast' } },
+      { id: 'implementation', parentId: 'parent' },
+      { id: 'evidence', parentId: 'parent' }
+    ],
+    lanes: [
+      { id: 'runtime', layer: 'implementation', allowedWrites: ['src/runtime/**'], evidencePrefix: 'evidence/runtime/' },
+      { id: 'tests', layer: 'evidence', allowedWrites: ['test/**'], evidencePrefix: 'evidence/tests/' }
+    ],
+    policy: { defaultCompute: 'fast' }
+  };
+}
+
+export function makeBenchTasks(count) {
+  const tasks = [];
+  for (let i = 0; i < count; i += 1) {
+    const lane = i % 3 === 0 ? 'tests' : 'runtime';
+    tasks.push({
+      id: 'task-' + i,
+      lane,
+      priority: i % 100,
+      targetRefs: [lane === 'tests' ? `test/file-${i}.mjs` : `src/runtime/file-${i}.ts`],
+      acceptance: ['task ' + i + ' passes']
+    });
+  }
+  return tasks;
+}
+
+export function makeBenchBundles(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;
+}
+
+export function makeBenchTraceBundles(plan, count, offset = 0) {
+  const bundles = [];
+  for (let i = 0; i < Math.min(count, plan.jobs.length); i += 1) {
+    const job = plan.jobs[(i + offset) % plan.jobs.length];
+    const region = `region.${i % 8}`;
+    const traceShard = createSwarmTraceShard({
+      jobId: job.id,
+      lane: job.lane,
+      subject: 'bench-trace',
+      rowWindows: [{ start: i * 10, end: i * 10 + 4, rowCount: 5, firstDivergenceAt: i % 5 === 0 ? i * 10 + 2 : undefined, deltaFields: ['state.value'] }],
+      hypotheses: [{ sourcePath: job.task.targetRefs[0], symbol: `benchSymbol${i}`, region, confidence: i % 5 === 0 ? 'high' : 'medium' }],
+      executableOwnershipRegions: [{
+        id: region,
+        sourcePath: job.task.targetRefs[0],
+        symbol: `benchSymbol${i}`,
+        selectors: [`${region}.*`],
+        affectedTests: ['node trace-gate.mjs'],
+        riskLevel: i % 5 === 0 ? 'medium' : 'low'
+      }],
+      focusedTests: ['node trace-gate.mjs'],
+      referenceEvidence: [{ path: `agent-runs/bench/${job.id}/reference-trace.jsonl`, kind: 'trace' }]
+    });
+    bundles.push(createSwarmMergeBundle({
+      job,
+      result: {
+        jobId: job.id,
+        status: 'verified',
+        changedPaths: [job.task.targetRefs[0] ?? `src/runtime/file-${i}.ts`],
+        changedRegions: [region],
+        verification: [{ status: 0 }]
+      },
+      patchPath: `agent-runs/bench/${job.id}/changes.patch`,
+      traceShards: [traceShard]
+    }));
+  }
+  return bundles;
+}

package/benchmarks/package-bench-rows.mjs

@@ -0,0 +1,190 @@
+import {
+  checkSwarmOwnership,
+  createSwarmAdaptiveLoadPlan,
+  createSwarmContextPack,
+  createSwarmHotspotReport,
+  createSwarmLanePlaybook,
+  createSwarmMergeAdmission,
+  createSwarmManifest,
+  createSwarmEventStream,
+  createSwarmLeases,
+  createSwarmMergeBundle,
+  createSwarmMergeIndex,
+  createSwarmOracleCorpus,
+  createSwarmPatchStackPlan,
+  createSwarmReplayBundle,
+  createSwarmParityOracle,
+  createSwarmDivergenceReport,
+  createSwarmWatchpointPlan,
+  createSwarmDebugHandoff,
+  createSwarmEvidenceIndex,
+  createSwarmBlackboard,
+  createSwarmBottleneckReport,
+  createSwarmFixtureCatalog,
+  createSwarmProgressModel,
+  createSwarmPlan,
+  createSwarmProof,
+  createSwarmQueueOverlay,
+  createSwarmQueueSnapshot,
+  createSwarmRun,
+  createSwarmRunCheckpoint,
+  createSwarmSchedule,
+  createSwarmTraceIndex,
+  decodeSwarmJsonl,
+  defineSwarmTasks,
+  encodeSwarmJsonl,
+  querySwarmTraceIndex,
+  routeSwarmEventToMailboxes,
+  resolveSwarmCompute,
+  validateSwarmManifest
+} from '../dist/index.js';
+import {
+  makeBenchBundles,
+  makeBenchManifest,
+  makeBenchTasks,
+  makeBenchTraceBundles
+} from './package-bench-fixtures.mjs';
+
+export function createPackageBenchRows({ taskCount, measure }) {
+  const manifest = createSwarmManifest(makeBenchManifest());
+  const tasks = defineSwarmTasks(makeBenchTasks(taskCount));
+  let plan = createSwarmPlan(manifest, tasks, { limit: 64 });
+  let run = createSwarmRun({ plan });
+  let jsonl = encodeSwarmJsonl([plan, run]);
+  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 = makeBenchBundles(plan, 32);
+  let mergeIndex = createSwarmMergeIndex({ bundles });
+
+  return [
+    measure('create-plan-' + taskCount, 8, () => {
+      plan = createSwarmPlan(manifest, tasks, { limit: 64, selectors: ['task'] });
+      return plan.jobs.length;
+    }),
+    measure('validate-manifest', 32, () => validateSwarmManifest(manifest).issues.length),
+    measure('resolve-compute-' + taskCount, 64, () => resolveSwarmCompute(manifest, tasks[cursor++ % tasks.length]).id.length),
+    measure('ownership-check-' + taskCount, 64, () => checkSwarmOwnership(plan.jobs[cursor++ % plan.jobs.length], ['src/runtime/file.ts']).violations.length),
+    measure('create-run-' + taskCount, 16, () => {
+      run = createSwarmRun({ plan });
+      return run.jobs.length;
+    }),
+    measure('jsonl-encode', 16, () => {
+      jsonl = encodeSwarmJsonl([plan, run]);
+      return jsonl.length;
+    }),
+    measure('jsonl-decode', 16, () => decodeSwarmJsonl(jsonl).length),
+    measure('proof', 16, () => createSwarmProof(plan).hash.length),
+    measure('schedule-lease-' + taskCount, 8, () => {
+      schedule = createSwarmSchedule({ plan, maxReadyJobs: 128, maxComputeConcurrency: { fast: 64, deep: 32 } });
+      leases = createSwarmLeases({ schedule, workerId: 'bench-worker', now: 1000 + cursor++, leaseMs: 60000, count: 16 });
+      return schedule.ready.length + leases.length;
+    }),
+    measure('adaptive-load-' + taskCount, 8, () => createSwarmAdaptiveLoadPlan({
+      plan,
+      schedule,
+      mode: 'balanced',
+      maxLimits: { maxReadyJobs: 128 },
+      currentLimits: { maxReadyJobs: 64 },
+      observations: [
+        { kind: 'semantic-empty', jobId: plan.jobs[cursor % plan.jobs.length].id, lane: plan.jobs[cursor % plan.jobs.length].lane },
+        { kind: 'log-noise', lane: 'runtime', value: 200000 }
+      ],
+      generatedAt: 1500 + cursor++
+    }).summary.decisionCount),
+    measure('queue-snapshot-' + taskCount, 8, () => {
+      const snapshot = createSwarmQueueSnapshot({ plan, run, leases, generatedAt: 2000 + cursor++ });
+      return snapshot.summary.jobCount + snapshot.summary.leaseCount;
+    }),
+    measure('run-checkpoint-' + taskCount, 16, () => createSwarmRunCheckpoint({ run, sequence: cursor++ }).hash.length),
+    measure('merge-bundle-' + taskCount, 32, () => createSwarmMergeBundle({
+      job: plan.jobs[cursor % plan.jobs.length],
+      result: {
+        jobId: plan.jobs[cursor++ % plan.jobs.length].id,
+        status: 'completed',
+        changedPaths: ['src/runtime/file.ts'],
+        verification: [{ status: 0 }]
+      },
+      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 = makeBenchBundles(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('replay-debug-evidence-' + taskCount, 16, () => {
+      const replay = createSwarmReplayBundle({
+        commands: ['node replay.mjs'],
+        artifacts: [{ path: 'agent-runs/bench/trace.jsonl', kind: 'trace' }],
+        expectedEvidence: ['trace.jsonl']
+      });
+      const parity = createSwarmParityOracle({
+        comparators: [{ status: 'failed', expected: 1, actual: 2, operationIndex: cursor++ }]
+      });
+      const divergence = createSwarmDivergenceReport({
+        replayBundleIds: [replay.id],
+        observabilityPoints: [{ operationIndex: cursor, path: '/value' }],
+        expected: 1,
+        actual: 2
+      });
+      const watch = createSwarmWatchpointPlan({ watchpoints: [{ path: '/value', operator: 'changes' }] });
+      const handoff = createSwarmDebugHandoff({
+        replayBundleIds: [replay.id],
+        divergenceReportIds: [divergence.id],
+        watchpointPlanIds: [watch.id],
+        comparisons: parity.comparators
+      });
+      const evidence = createSwarmEvidenceIndex({ entries: [{ topic: 'bench', path: 'agent-runs/bench/evidence.json' }] });
+      const blackboard = createSwarmBlackboard({ entries: [{ topic: 'bench', text: 'divergence found', sourceIds: [divergence.id] }] });
+      const bottleneck = createSwarmBottleneckReport({ sources: [{ text: 'merge review bottleneck', changedPaths: ['src/runtime.ts'] }] });
+      const fixtures = createSwarmFixtureCatalog({ fixtures: [{ id: 'logged-in', tags: ['auth'] }] });
+      const progress = createSwarmProgressModel({ items: [{ id: 'bench', status: 'accepted' }] });
+      return handoff.commands.length + evidence.summary.entryCount + blackboard.summary.entryCount + bottleneck.summary.kindCount + fixtures.summary.fixtureCount + progress.summary.acceptedCount;
+    }),
+    measure('trace-index-' + taskCount, 16, () => {
+      const traceBundles = makeBenchTraceBundles(plan, 24, cursor++);
+      const traceIndex = createSwarmTraceIndex({ bundles: traceBundles, generatedAt: 7000 + cursor++ });
+      const query = querySwarmTraceIndex(traceIndex, { region: 'region.2', textIncludes: 'benchSymbol' });
+      return traceIndex.summary.shardCount + traceIndex.summary.executableOwnershipRegionCount + query.summary.shardCount;
+    }),
+    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;
+    })
+  ];
+}

package/benchmarks/package-bench-runtime.mjs

@@ -0,0 +1,94 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { fileURLToPath } from 'node:url';
+
+export function createPackageBenchPaths(metaUrl) {
+  const dirname = path.dirname(fileURLToPath(metaUrl));
+  const packageDir = path.resolve(dirname, '..');
+  return {
+    packageDir,
+    repoRoot: path.basename(path.dirname(packageDir)) === 'packages'
+      ? path.resolve(packageDir, '..', '..')
+      : packageDir
+  };
+}
+
+export function createMeasure(rounds) {
+  return function measure(fixture, operationsPerRound, fn) {
+    const samples = [];
+    let checksum = 0;
+    for (let round = 0; round < rounds; round += 1) {
+      const start = performance.now();
+      for (let op = 0; op < operationsPerRound; op += 1) checksum += Number(fn()) || 0;
+      const elapsed = performance.now() - start;
+      samples.push((elapsed * 1000) / operationsPerRound);
+    }
+    samples.sort((a, b) => a - b);
+    return {
+      fixture,
+      operationsPerRound,
+      medianUs: percentile(samples, 0.5),
+      p95Us: percentile(samples, 0.95),
+      checksum
+    };
+  };
+}
+
+export function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--out') out.out = argv[++i];
+    else if (argv[i] === '--tasks') out.tasks = argv[++i];
+    else if (argv[i] === '--rounds') out.rounds = argv[++i];
+  }
+  return out;
+}
+
+export function readPositiveInt(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+
+export function resolveOutPath(repoRoot, out) {
+  return out ? path.resolve(repoRoot, out) : null;
+}
+
+export function readPackageVersion(packageDir) {
+  return JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8')).version;
+}
+
+export function writeBenchReport(report, outPath) {
+  if (!outPath) return;
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, JSON.stringify(report, null, 2) + '\n');
+}
+
+export function printBenchReport(report, { outPath, repoRoot }) {
+  console.log(report.package + ' package benchmark');
+  console.log('Node ' + report.node + ' on ' + report.platform + ', tasks=' + report.taskCount + ', rounds=' + report.rounds);
+  console.log('These are Frontier-only package measurements, not competitor comparisons.');
+  console.log('');
+  console.log(padRight('Fixture', 30) + padLeft('Median', 12) + padLeft('p95', 12));
+  for (const row of report.rows) {
+    console.log(padRight(row.fixture, 30) + padLeft(formatUs(row.medianUs), 12) + padLeft(formatUs(row.p95Us), 12));
+  }
+  if (outPath) console.log('\nwrote ' + path.relative(repoRoot, outPath));
+}
+
+export function formatUs(value) {
+  if (value >= 1000) return (value / 1000).toFixed(2) + 'ms';
+  return value.toFixed(2) + 'us';
+}
+
+function padRight(value, size) {
+  return String(value).padEnd(size);
+}
+
+function padLeft(value, size) {
+  return String(value).padStart(size);
+}
+
+function percentile(sorted, pct) {
+  return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * pct))];
+}