@shapeshift-labs/frontier-swarm 0.5.8 → 0.5.10

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.
@@ -282,7 +282,7 @@ 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 ownership regions, proof/spec obligations, source projection/native compile readiness, and empty sidecar detection,
+- job results, merge bundles, queue overlays, and merge indexes can carry `semanticImport` summaries for imported symbols, 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,
 - `createSwarmQueueOverlay` and `deriveSwarmQueueStatus` keep central queue files immutable while deriving status from worker result overlays,
@@ -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.mjs

@@ -33,9 +33,12 @@ import {
   createSwarmRun,
   createSwarmRunCheckpoint,
   createSwarmSchedule,
+  createSwarmTraceIndex,
+  createSwarmTraceShard,
   decodeSwarmJsonl,
   defineSwarmTasks,
   encodeSwarmJsonl,
+  querySwarmTraceIndex,
   routeSwarmEventToMailboxes,
   resolveSwarmCompute,
   validateSwarmManifest
@@ -169,6 +172,12 @@ const rows = [
     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 = makeTraceBundles(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,
@@ -266,6 +275,44 @@ function makeBundles(plan, count) {
   return bundles;
 }
 
+function makeTraceBundles(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;
+}
+
 function measure(fixture, operationsPerRound, fn) {
   const samples = [];
   let checksum = 0;

package/dist/index.d.ts

@@ -53,6 +53,10 @@ export declare const FRONTIER_SWARM_PARITY_ORACLE_KIND = "frontier.swarm.parity-
 export declare const FRONTIER_SWARM_PARITY_ORACLE_VERSION = 1;
 export declare const FRONTIER_SWARM_DIVERGENCE_REPORT_KIND = "frontier.swarm.divergence-report";
 export declare const FRONTIER_SWARM_DIVERGENCE_REPORT_VERSION = 1;
+export declare const FRONTIER_SWARM_TRACE_SHARD_KIND = "frontier.swarm.trace-shard";
+export declare const FRONTIER_SWARM_TRACE_SHARD_VERSION = 1;
+export declare const FRONTIER_SWARM_TRACE_INDEX_KIND = "frontier.swarm.trace-index";
+export declare const FRONTIER_SWARM_TRACE_INDEX_VERSION = 1;
 export declare const FRONTIER_SWARM_OBSERVABILITY_POINT_KIND = "frontier.swarm.observability-point";
 export declare const FRONTIER_SWARM_OBSERVABILITY_POINT_VERSION = 1;
 export declare const FRONTIER_SWARM_WATCHPOINT_PLAN_KIND = "frontier.swarm.watchpoint-plan";
@@ -108,6 +112,7 @@ export type FrontierSwarmPatchStatus = 'unknown' | 'applies' | 'missing' | 'stal
 export type FrontierSwarmQueueOverlayStatus = 'satisfied' | 'ready-to-apply' | 'needs-human-port' | 'failed-evidence' | 'stale-against-head' | 'discovery-only' | 'blocked' | 'rejected' | 'unknown' | string;
 export type FrontierSwarmParityOracleStatus = 'pending' | 'passed' | 'failed' | 'blocked' | 'skipped' | string;
 export type FrontierSwarmDivergenceSeverity = 'info' | 'warning' | 'error' | 'critical' | string;
+export type FrontierSwarmTraceShardStatus = 'passed' | 'failed' | 'blocked' | 'unknown' | string;
 export type FrontierSwarmWatchpointAction = 'break' | 'log' | 'capture' | 'handoff' | string;
 export type FrontierSwarmBottleneckKind = 'correctness' | 'performance' | 'instrumentation-overhead' | 'missing-oracle' | 'flaky-harness' | 'blocked-dependency' | 'merge-review' | 'resource-capacity' | 'budget' | 'queue' | string;
 export type FrontierSwarmConfidence = 'low' | 'medium' | 'high' | string;
@@ -1025,6 +1030,41 @@ export interface FrontierSwarmNativeCompileSummaryInput {
     needsReview?: number;
     blocked?: number;
 }
+export interface FrontierSwarmParadigmSemanticsSummaryInput {
+    total?: number;
+    ids?: readonly string[];
+    groups?: readonly string[];
+    kinds?: readonly string[];
+    evidence?: number;
+    bindingScopes?: number;
+    bindings?: number;
+    patterns?: number;
+    typeConstraints?: number;
+    evaluationModels?: number;
+    memoryLocations?: number;
+    effectRegions?: number;
+    controlRegions?: number;
+    logicPrograms?: number;
+    actorSystems?: number;
+    stackEffects?: number;
+    arrayShapes?: number;
+    numericKernels?: number;
+    dataflowNetworks?: number;
+    clockModels?: number;
+    objectModels?: number;
+    macroExpansions?: number;
+    reflectionBoundaries?: number;
+    loweringRecords?: number;
+    byGroup?: FrontierSwarmSemanticImportCounterInput;
+    byKind?: FrontierSwarmSemanticImportCounterInput;
+    hasRuntimeSemantics?: boolean;
+    hasLogicSemantics?: boolean;
+    hasStackSemantics?: boolean;
+    hasArraySemantics?: boolean;
+    hasMacroOrReflection?: boolean;
+    hasLowering?: boolean;
+    empty?: boolean;
+}
 export interface FrontierSwarmSemanticImportSummaryInput {
     total?: number;
     selected?: number;
@@ -1040,6 +1080,7 @@ export interface FrontierSwarmSemanticImportSummaryInput {
     semanticIndex?: FrontierSwarmSemanticIndexSummaryInput;
     semanticSidecars?: FrontierSwarmSemanticSidecarSummaryInput;
     proofSpec?: FrontierSwarmProofSpecSummaryInput;
+    paradigmSemantics?: FrontierSwarmParadigmSemanticsSummaryInput;
     sourceProjections?: FrontierSwarmSourceProjectionSummaryInput;
     nativeCompiles?: FrontierSwarmNativeCompileSummaryInput;
     readiness?: FrontierSwarmSemanticImportCounterInput;
@@ -1126,6 +1167,41 @@ export interface FrontierSwarmNativeCompileSummary {
     needsReview: number;
     blocked: number;
 }
+export interface FrontierSwarmParadigmSemanticsSummary {
+    total: number;
+    ids: string[];
+    groups: string[];
+    kinds: string[];
+    evidence: number;
+    bindingScopes: number;
+    bindings: number;
+    patterns: number;
+    typeConstraints: number;
+    evaluationModels: number;
+    memoryLocations: number;
+    effectRegions: number;
+    controlRegions: number;
+    logicPrograms: number;
+    actorSystems: number;
+    stackEffects: number;
+    arrayShapes: number;
+    numericKernels: number;
+    dataflowNetworks: number;
+    clockModels: number;
+    objectModels: number;
+    macroExpansions: number;
+    reflectionBoundaries: number;
+    loweringRecords: number;
+    byGroup: Record<string, number>;
+    byKind: Record<string, number>;
+    hasRuntimeSemantics: boolean;
+    hasLogicSemantics: boolean;
+    hasStackSemantics: boolean;
+    hasArraySemantics: boolean;
+    hasMacroOrReflection: boolean;
+    hasLowering: boolean;
+    empty: boolean;
+}
 export interface FrontierSwarmSemanticImportSummary {
     total: number;
     selected: number;
@@ -1141,6 +1217,7 @@ export interface FrontierSwarmSemanticImportSummary {
     semanticIndex: FrontierSwarmSemanticIndexSummary;
     semanticSidecars: FrontierSwarmSemanticSidecarSummary;
     proofSpec: FrontierSwarmProofSpecSummary;
+    paradigmSemantics: FrontierSwarmParadigmSemanticsSummary;
     sourceProjections: FrontierSwarmSourceProjectionSummary;
     nativeCompiles: FrontierSwarmNativeCompileSummary;
     readiness: Record<string, number>;
@@ -1233,6 +1310,7 @@ export interface FrontierSwarmMergeBundleInput {
     branchName?: string;
     commit?: string;
     semanticImport?: FrontierSwarmSemanticImportSummaryInput;
+    traceShards?: readonly (FrontierSwarmTraceShard | FrontierSwarmTraceShardInput)[];
     metadata?: unknown;
     generatedAt?: number;
 }
@@ -1268,6 +1346,7 @@ export interface FrontierSwarmMergeBundle {
     staleAgainstHead: boolean;
     reasons: string[];
     semanticImport?: FrontierSwarmSemanticImportSummary;
+    traceShards: FrontierSwarmTraceShard[];
     metadata?: JsonObject;
 }
 export interface FrontierSwarmQueueOverlayInput {
@@ -1808,6 +1887,166 @@ export interface FrontierSwarmDivergenceReport {
     generatedAt: number;
     metadata?: JsonObject;
 }
+export interface FrontierSwarmTraceRowWindowInput {
+    id?: string;
+    title?: string;
+    start?: number;
+    end?: number;
+    rowCount?: number;
+    firstDivergenceAt?: number;
+    deltaFields?: readonly string[];
+    evidenceRefs?: readonly (string | FrontierSwarmNamedRefInput)[];
+    metadata?: unknown;
+}
+export interface FrontierSwarmTraceRowWindow {
+    id: string;
+    title: string;
+    start?: number;
+    end?: number;
+    rowCount?: number;
+    firstDivergenceAt?: number;
+    deltaFields: string[];
+    evidenceRefs: FrontierSwarmNamedRef[];
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmTraceHypothesisInput {
+    id?: string;
+    title?: string;
+    sourcePath?: string;
+    line?: number;
+    symbol?: string;
+    region?: string;
+    confidence?: FrontierSwarmConfidence;
+    reason?: string;
+    evidenceRefs?: readonly (string | FrontierSwarmNamedRefInput)[];
+    metadata?: unknown;
+}
+export interface FrontierSwarmTraceHypothesis {
+    id: string;
+    title: string;
+    sourcePath?: string;
+    line?: number;
+    symbol?: string;
+    region?: string;
+    confidence: FrontierSwarmConfidence;
+    reason?: string;
+    evidenceRefs: FrontierSwarmNamedRef[];
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmExecutableOwnershipRegionInput {
+    id: string;
+    kind?: string;
+    sourcePath?: string;
+    symbol?: string;
+    selectors?: readonly string[];
+    affectedTests?: readonly (string | FrontierSwarmCommandInput)[];
+    conflictingAssumptions?: readonly string[];
+    traceRefs?: readonly (string | FrontierSwarmNamedRefInput)[];
+    riskLevel?: FrontierSwarmRiskLevel;
+    metadata?: unknown;
+}
+export interface FrontierSwarmExecutableOwnershipRegion {
+    id: string;
+    kind: string;
+    sourcePath?: string;
+    symbol?: string;
+    selectors: string[];
+    affectedTests: FrontierSwarmCommand[];
+    conflictingAssumptions: string[];
+    traceRefs: FrontierSwarmNamedRef[];
+    riskLevel: FrontierSwarmRiskLevel;
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmTraceShardInput {
+    id?: string;
+    jobId?: string;
+    lane?: string;
+    subject?: string;
+    status?: FrontierSwarmTraceShardStatus;
+    traceRefs?: readonly (string | FrontierSwarmNamedRefInput)[];
+    divergence?: FrontierSwarmDivergenceReport | FrontierSwarmDivergenceReportInput;
+    rowWindows?: readonly FrontierSwarmTraceRowWindowInput[];
+    hypotheses?: readonly FrontierSwarmTraceHypothesisInput[];
+    executableOwnershipRegions?: readonly FrontierSwarmExecutableOwnershipRegionInput[];
+    focusedTests?: readonly (string | FrontierSwarmCommandInput)[];
+    referenceEvidence?: readonly (string | FrontierSwarmNamedRefInput)[];
+    generatedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmTraceShard {
+    kind: typeof FRONTIER_SWARM_TRACE_SHARD_KIND;
+    version: typeof FRONTIER_SWARM_TRACE_SHARD_VERSION;
+    id: string;
+    jobId?: string;
+    lane?: string;
+    subject?: string;
+    status: FrontierSwarmTraceShardStatus;
+    traceRefs: FrontierSwarmNamedRef[];
+    divergence?: FrontierSwarmDivergenceReport;
+    rowWindows: FrontierSwarmTraceRowWindow[];
+    hypotheses: FrontierSwarmTraceHypothesis[];
+    executableOwnershipRegions: FrontierSwarmExecutableOwnershipRegion[];
+    focusedTests: FrontierSwarmCommand[];
+    referenceEvidence: FrontierSwarmNamedRef[];
+    generatedAt: number;
+    summary: {
+        rowWindowCount: number;
+        hypothesisCount: number;
+        executableOwnershipRegionCount: number;
+        focusedTestCount: number;
+        referenceEvidenceCount: number;
+        hasDivergence: boolean;
+    };
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmTraceIndexInput {
+    id?: string;
+    shards?: readonly (FrontierSwarmTraceShard | FrontierSwarmTraceShardInput)[];
+    bundles?: readonly FrontierSwarmMergeBundle[];
+    generatedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmTraceIndex {
+    kind: typeof FRONTIER_SWARM_TRACE_INDEX_KIND;
+    version: typeof FRONTIER_SWARM_TRACE_INDEX_VERSION;
+    id: string;
+    generatedAt: number;
+    shards: FrontierSwarmTraceShard[];
+    byJobId: Record<string, FrontierSwarmTraceShard[]>;
+    bySubject: Record<string, FrontierSwarmTraceShard[]>;
+    byRegion: Record<string, FrontierSwarmTraceShard[]>;
+    bySourcePath: Record<string, FrontierSwarmTraceShard[]>;
+    summary: {
+        shardCount: number;
+        rowWindowCount: number;
+        hypothesisCount: number;
+        executableOwnershipRegionCount: number;
+        focusedTestCount: number;
+        referenceEvidenceCount: number;
+        divergenceCount: number;
+    };
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmTraceIndexQuery {
+    jobId?: string;
+    lane?: string;
+    subject?: string;
+    region?: string;
+    sourcePath?: string;
+    status?: FrontierSwarmTraceShardStatus;
+    minConfidence?: number;
+    hasDivergence?: boolean;
+    textIncludes?: string;
+}
+export interface FrontierSwarmTraceIndexQueryResult {
+    shards: FrontierSwarmTraceShard[];
+    summary: {
+        shardCount: number;
+        rowWindowCount: number;
+        hypothesisCount: number;
+        executableOwnershipRegionCount: number;
+    };
+}
 export interface FrontierSwarmWatchpointInput {
     id?: string;
     title?: string;
@@ -2566,6 +2805,7 @@ export interface FrontierSwarmCoordinatorDashboardInput {
     mergeIndex?: FrontierSwarmMergeIndex;
     queueOverlay?: FrontierSwarmQueueOverlay;
     evidenceIndex?: FrontierSwarmEvidenceIndex;
+    traceIndex?: FrontierSwarmTraceIndex;
     admission?: FrontierSwarmMergeAdmission;
     processes?: readonly FrontierSwarmCoordinatorProcessInput[];
     generatedAt?: number;
@@ -2587,6 +2827,7 @@ export interface FrontierSwarmCoordinatorDashboard {
     mergeIndex?: FrontierSwarmMergeIndex;
     queueOverlay?: FrontierSwarmQueueOverlay;
     evidenceIndex?: FrontierSwarmEvidenceIndex;
+    traceIndex?: FrontierSwarmTraceIndex;
     admission?: FrontierSwarmMergeAdmission;
     summary: {
         jobCount: number;
@@ -2597,10 +2838,23 @@ export interface FrontierSwarmCoordinatorDashboard {
         duplicateGroupCount: number;
         semanticSidecarCount: number;
         semanticRegionCount: number;
+        traceShardCount: number;
+        traceDivergenceCount: number;
+        executableOwnershipRegionCount: number;
         averageMergeScore: number;
     };
     metadata?: JsonObject;
 }
+export interface FrontierSwarmCoordinatorTraceSummary {
+    shardCount: number;
+    rowWindowCount: number;
+    hypothesisCount: number;
+    executableOwnershipRegionCount: number;
+    focusedTestCount: number;
+    referenceEvidenceCount: number;
+    divergenceCount: number;
+    openDivergenceCount: number;
+}
 export interface FrontierSwarmCoordinatorJob {
     jobId: string;
     taskId?: string;
@@ -2632,6 +2886,7 @@ export interface FrontierSwarmCoordinatorJob {
         requiredFailed: number;
     };
     semanticImport?: FrontierSwarmSemanticImportSummary;
+    traceSummary?: FrontierSwarmCoordinatorTraceSummary;
     generatedAt: number;
 }
 export interface FrontierSwarmCoordinatorDuplicateGroup {
@@ -2650,6 +2905,9 @@ export interface FrontierSwarmCoordinatorDashboardQuery {
     region?: string;
     hasSemanticImport?: boolean;
     hasSemanticRegions?: boolean;
+    hasTraceShards?: boolean;
+    traceSubject?: string;
+    traceRegion?: string;
     staleAgainstHead?: boolean;
     duplicateOnly?: boolean;
     minMergeScore?: number;
@@ -2802,6 +3060,9 @@ export declare function createSwarmObservabilityPoint(input?: FrontierSwarmObser
 export declare function createSwarmReplayBundle(input?: FrontierSwarmReplayBundleInput): FrontierSwarmReplayBundle;
 export declare function createSwarmParityOracle(input?: FrontierSwarmParityOracleInput): FrontierSwarmParityOracle;
 export declare function createSwarmDivergenceReport(input?: FrontierSwarmDivergenceReportInput): FrontierSwarmDivergenceReport;
+export declare function createSwarmTraceShard(input?: FrontierSwarmTraceShardInput): FrontierSwarmTraceShard;
+export declare function createSwarmTraceIndex(input?: FrontierSwarmTraceIndexInput): FrontierSwarmTraceIndex;
+export declare function querySwarmTraceIndex(index: FrontierSwarmTraceIndex, query?: FrontierSwarmTraceIndexQuery): FrontierSwarmTraceIndexQueryResult;
 export declare function createSwarmWatchpointPlan(input?: FrontierSwarmWatchpointPlanInput): FrontierSwarmWatchpointPlan;
 export declare function createSwarmDebugHandoff(input?: FrontierSwarmDebugHandoffInput): FrontierSwarmDebugHandoff;
 export declare function createSwarmInstrumentationBudget(input?: FrontierSwarmInstrumentationBudgetInput): FrontierSwarmInstrumentationBudget;