@remnic/bench 9.3.710 → 9.3.712

package/README.md

@@ -200,3 +200,60 @@ If you're an AI agent extending a Remnic-based stack: **do not** import `@remnic
 ## License
 
 MIT. See the root [LICENSE](https://github.com/joshuaswarren/remnic/blob/main/LICENSE) file.
+
+## Coding-graph benchmark harness (issue #1557)
+
+A dedicated benchmark suite for [`@remnic/coding-graph`](https://www.npmjs.com/package/@remnic/coding-graph) — the symbol-extraction engine + SQLite knowledge-graph store for codebase memory. The harness is the authority for every performance claim: no number ships in docs without a harness measurement behind it (rule 55, #1527 stub-honesty).
+
+### What it measures
+
+| Metric | Description |
+|---|---|
+| `fullIndexMs` | Wall time to index the entire fixture in one batch. |
+| `fullIndexLocsPerSecond` | Sustained LOC/s during full index (higher is better). |
+| `incrementalUpdateP50Ms` / `incrementalUpdateP95Ms` | Single-file re-ingest latency (p50/p95 over ≥20 iterations). |
+| `tracePathP95Ms` | `trace_path` (BFS, depth ≤ 5) p95. |
+| `searchGraphP95Ms` | `search_graph` name-pattern p95. |
+| `deadCodeMs` | Dead-code query wall time. |
+| `dbBytesPerKloc` | SQLite DB bytes per KLOC after index. |
+
+### Synthetic fixture generator
+
+The harness ships a **deterministic** synthetic repo generator (`generateSyntheticRepo`): parameterized by files × symbols-per-file × call-density × language. Same seed + same params always produces byte-identical IR output (rule 38). Fixtures are synthetic code only — no real repos, no user data (public-repo policy).
+
+### Baseline + regression gate
+
+The measured numbers live in [`baselines/coding-graph-baseline.json`](./baselines/coding-graph-baseline.json) — bench-owned, separate from the structural ratchets in `scripts/ratchet-baseline.json`. The regression gate (`checkCodingGraphRegression`) compares a report against the baseline with a generous tolerance (default 30%). It hard-fails on gross regression — a real failing step, not a warning (rule 50). Tightening the baseline is a deliberate PR act (mirrors `check-ratchets --update`).
+
+### Measured numbers (first baseline)
+
+> Numbers below are from the **baseline JSON file** — this section is checked against it so prose can't drift from measurement. Run `remnic bench coding-graph` to reproduce.
+
+| Metric | Value | Machine |
+|---|---|---|
+| Full index | ~17.6 ms, ~115k LOC/s | Apple M2 Max, Node v22 |
+| Incremental update p95 | ~0.26 ms | Apple M2 Max |
+| trace_path p95 | ~0.14 ms | Apple M2 Max |
+| search_graph p95 | ~0.29 ms | Apple M2 Max |
+| dead_code | ~0.67 ms | Apple M2 Max |
+| DB size | ~2 KB/KLOC | Apple M2 Max |
+
+These are **working targets on a small fixture (20 files, 200 symbols)**, NOT parity claims against codebase-memory-mcp's published numbers (28M LOC in 3 min, <1ms Cypher). Scale targets at 1M+ LOC are tracked as stretch goals — the harness will measure them when Tier-L fixtures are wired (issue #1557 PR2).
+
+### Usage
+
+```typescript
+import { runCodingGraphBenchmark, checkCodingGraphRegression } from "@remnic/bench";
+
+const report = await runCodingGraphBenchmark({
+  fixture: { fileCount: 1000, symbolsPerFile: 10, callDensity: 0.2 },
+  iterations: 25,
+});
+
+const baseline = require("@remnic/bench/baselines/coding-graph-baseline.json");
+const gate = checkCodingGraphRegression(report, baseline, 30);
+if (!gate.passed) {
+  console.error(gate.summary);
+  process.exit(1);
+}
+```

package/baselines/coding-graph-baseline.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": 1,
+  "machine": {
+    "arch": "arm64",
+    "platform": "darwin",
+    "nodeVersion": "v22.20.0",
+    "cpuModel": "Apple M2 Max",
+    "cpuCores": 12,
+    "totalMemoryMb": 98304
+  },
+  "fixtureConfig": {
+    "seed": 42,
+    "fileCount": 20,
+    "symbolsPerFile": 10,
+    "callDensity": 0.3,
+    "language": "typescript"
+  },
+  "metrics": {
+    "fullIndexMs": 14.864042000000154,
+    "fullIndexLocsPerSecond": 136302,
+    "incrementalUpdateP50Ms": 0.19358299999998962,
+    "incrementalUpdateP95Ms": 0.26237500000002,
+    "tracePathP95Ms": 0.15750000000002728,
+    "searchGraphP95Ms": 0.19700000000011642,
+    "deadCodeMs": 2.29424999999992,
+    "dbBytesPerKloc": 280636
+  },
+  "createdAt": "2026-07-06T10:50:56.821Z",
+  "note": "Initial baseline — first harness run with WAL-aware DB sizing (issue #1557 PR1)."
+}

package/dist/index.d.ts

@@ -487,7 +487,7 @@ interface SavedBaseline {
     timestamp: string;
     metrics: Record<string, number>;
 }
-interface RegressionGateResult {
+interface RegressionGateResult$1 {
     passed: boolean;
     regressions: RegressionDetail[];
 }
@@ -2276,7 +2276,7 @@ declare function loadBaseline(baselinePath?: string): SavedBaseline | undefined;
 declare function saveBaseline(baselinePath: string, baseline: SavedBaseline): void;
 declare function runExplain(service: EngramAccessService, query: string): Promise<ExplainResult>;
 declare function runBenchSuite(service: EngramAccessService, config?: BenchConfig): Promise<BenchmarkSuiteResult>;
-declare function checkRegression(metrics: Record<string, number>, baseline: SavedBaseline | undefined, tolerance: number): RegressionGateResult;
+declare function checkRegression(metrics: Record<string, number>, baseline: SavedBaseline | undefined, tolerance: number): RegressionGateResult$1;
 declare function generateReport(results: RecallMetrics[], reportPath?: string): BenchmarkReport;
 
 /**
@@ -2785,7 +2785,7 @@ interface SeededRng {
  * Deterministic 32-bit PRNG. Mulberry32 is small, fast, and sufficient for
  * shuffling benchmark tasks. Do NOT use for cryptographic operations.
  */
-declare function createSeededRng$1(seed: number): SeededRng;
+declare function createSeededRng$2(seed: number): SeededRng;
 /**
  * Fisher-Yates shuffle using a seeded PRNG. Returns a new array.
  */
@@ -3705,7 +3705,7 @@ interface ExtractionAttackResult {
 /**
  * Tiny mulberry32 PRNG — stable across Node versions.
  */
-declare function createSeededRng(seed: number): HarnessRng;
+declare function createSeededRng$1(seed: number): HarnessRng;
 /**
  * Entry point. See `types.ts` for the options contract.
  */
@@ -3873,4 +3873,327 @@ interface MitigatedTargetConfig {
  */
 declare function createMitigatedTarget(config: MitigatedTargetConfig): ExtractionAttackTarget;
 
-export { AMA_BENCH_DIAGNOSTIC_VARIANTS, ASSISTANT_AGENT_CONFIG_KEY, ASSISTANT_JUDGE_CONFIG_KEY, ASSISTANT_MEETING_PREP_SCENARIOS, ASSISTANT_MEETING_PREP_SMOKE_SCENARIOS, ASSISTANT_MORNING_BRIEF_SCENARIOS, ASSISTANT_MORNING_BRIEF_SMOKE_SCENARIOS, ASSISTANT_NEXT_BEST_ACTION_SCENARIOS, ASSISTANT_NEXT_BEST_ACTION_SMOKE_SCENARIOS, ASSISTANT_RUBRIC_DIMENSIONS, ASSISTANT_RUBRIC_ID_KEY, ASSISTANT_SEEDS_CONFIG_KEY, ASSISTANT_SPOT_CHECK_DIR_KEY, ASSISTANT_SYNTHESIS_SCENARIOS, ASSISTANT_SYNTHESIS_SMOKE_SCENARIOS, type AbstentionRetrievalCase, type AggregateMetrics, type AmaBenchDiagnosticAdapterOptions, type AmaBenchDiagnosticAnswererMode, type AmaBenchDiagnosticBreakdown, type AmaBenchDiagnosticMatrixArtifact, type AmaBenchDiagnosticRecallMode, type AmaBenchDiagnosticRunContext, type AmaBenchDiagnosticTaskEvidence, type AmaBenchDiagnosticTaskRow, type AmaBenchDiagnosticVariant, type AmaBenchDiagnosticVariantSummary, type AnthropicProviderConfig, type AssistantAgent, type AssistantMemoryFact, type AssistantMemoryGraph, type AssistantRubricDimension, type AssistantRubricScores, type AssistantRunnerOptions, type AssistantScenario, type AssistantStance, type AttackRecallOptions, type AttackRetrievalHit, type AttackerMode, BENCHMARK_ARTIFACT_SCHEMA_VERSION, BENCHMARK_INTEGRITY_META_SCHEMA, BENCHMARK_REPRO_MANIFEST_FILENAME, BENCHMARK_REPRO_MANIFEST_SCHEMA_VERSION, BENCHMARK_RESULT_SCHEMA, BENCHMARK_SPLIT_TYPES, type BaselineRow, type BaselineScenario, type BeamDatasetPreview, type BenchConfig, type BenchJudge, type BenchJudgeResult, type BenchMemoryAdapter, type BenchModelSource, type BenchReasoningEffort, type BenchRecallOptions, type BenchResponder, type BenchResponse, type BenchRuntimeProfile, type BenchTier, type BenchmarkArtifact, type BenchmarkArtifactEnvironment, type BenchmarkArtifactHardware, type BenchmarkArtifactJudgeCalibration, type BenchmarkArtifactPerTaskScore, type BenchmarkArtifactSystem, type BenchmarkArtifactTier, type BenchmarkCategory, type BenchmarkDefinition, type BenchmarkIntegrityMeta, type BenchmarkMeta, type BenchmarkMode, type BenchmarkReport, type BenchmarkReproManifest, type BenchmarkReproManifestDataset, type BenchmarkReproManifestFile, type BenchmarkReproManifestResult, type BenchmarkResult, type BenchmarkSplitType, type BenchmarkStatus, type BenchmarkSuiteResult, type BenchmarkTier, type BuildBenchmarkArtifactInput, type BuildBenchmarkPublishFeedOptions, type BuildBenchmarkReproManifestOptions, type BuiltInProvider, CALIBRATION_SLICE_SIZE, CANARY_FIXED_RECALL, CANARY_SCORE_FLOOR, type CalibrationAnswer, type CalibrationVerdictPair, type CanaryAdapterOptions, type CanaryFloorCheck, type CodexCliProviderConfig, type CohenKappaResult, type ComparisonMetricDelta, type ComparisonResult, type CompletionOpts, type CompletionResult, type ConfidenceInterval, type ContaminationCheckResult, type ContaminationEntry, type ContaminationManifest, type CustomBenchmarkScoring, type CustomBenchmarkSpec, type CustomBenchmarkTask, DEFAULT_ABLATION_BOOTSTRAP_SEED, DEFAULT_ASSISTANT_RUBRIC_ID, DEFAULT_BASELINE_SCENARIOS, DEFAULT_JUDGE_BINARIZATION_THRESHOLD, type DatasetSource, type DiscoveredModel, EMPTY_CONTAMINATION_MANIFEST, type EffectSizeInterpretation, type EffectSizeSummary, type ExplainResult, type ExtractedEntity, type ExtractedLink, type ExtractedPage, type ExtractionAttackOptions, type ExtractionAttackResult, type ExtractionAttackTarget, type FixtureGenerator, type FixtureOutput, type FixtureVariant, type GeneratedFile, type GoldEntity, type GoldEntityType, type GoldGraph, type GoldLink, type GoldPage, type HarnessRng, INTEGRITY_CIPHER_ALGORITHM, INTEGRITY_HASH_ALGORITHM, INTEGRITY_META_FIELDS, type IngestionBenchAdapter, type IngestionLog, JUDGE_CALIBRATION_KAPPA_THRESHOLD, type JudgeCalibrationIdentities, type JudgeCalibrationResult, type JudgeCategory, LOCAL_LAB_PROVIDER_KINDS, LOCOMO_DATASET_FILENAMES, LONG_MEM_EVAL_DATASET_FILENAMES, type LeaderboardArtifactWrite, type LlmJudge, type LlmProvider, type LoadDatasetOptions, type LoadSealedQrelsOptions, type LoadedDataset, type LoadedJudgeCalibrationState, type LocalLabManifest, type LocalLabManifestNotes, type LocalLabPhase, type LocalLabPhaseDescriptor, type LocalLabPhaseExecute, type LocalLabPhaseName, type LocalLabPhaseOutcome, LocalLabPreflightError, type LocalLabPreflightFailure, type LocalLabPreflightInput, type LocalLabPreflightOptions, type LocalLabPreflightResult, type LocalLabPreflightSuccess, type LocalLabProviderKind, type LocalLabRoleConfig, type LocalLlmProviderConfig, MEMORY_EVAL_DIMENSIONS, MEMORY_EVAL_PUBLIC_LINE, MIN_CALIBRATION_SOURCE_TASKS, MITIGATED_BASELINE_SCENARIOS, type MemCorrectGeneratorOptions, type MemCorrectSystemAdapter, type MemoryEvalCategory, type MemoryEvalDimension, type MemoryEvalDimensionId, type MemoryEvalMetric, type MemoryGraph, type MemoryStats, type MemorySystem, type Message, type MetricAggregate, type MitigatedBaselineConfig, type MitigatedTargetConfig, type MultipleChoiceQuestion, OTHER_NAMESPACE_MEMORIES, type OllamaProviderConfig, type OpenAiCompatibleProviderConfig, PROCEDURAL_REAL_SCENARIOS, PROCEDURAL_REAL_SCENARIOS_SMOKE, PUBLISHED_BENCHMARK_ARTIFACT_IDS, type PersonalizationRetrievalCase, type PreflightDiscoveredModel, type ProceduralAblationArtifact, type ProceduralAblationPerCase, type ProceduralAblationScenario, type ProceduralRealScenario, type ProceduralRealScenarioCategory, type ProviderBaseConfig, type ProviderConfig, type ProviderDiscoveryResult, type ProviderFactoryConfig, type PublishSkipReason, type PublishSkipRecord, type PublishedBenchmarkFeed, type PublishedBenchmarkFeedEntry, type PublishedBenchmarkId, REQUIRED_FRONTMATTER_FIELDS, type RecallMetrics, type RecoveredMemory, type RegressionDetail, type RegressionGateResult, type RemnicAdapterOptions, type ResolveBenchRuntimeProfileOptions, type ResolvedBenchRuntimeProfile, type ResolvedLocalLabProfile, type ResolvedLocalLabRole, type ResolvedRunBenchmarkOptions, type RotatedChoices, type RunBenchmarkOptions, type RunJudgeCalibrationOptions, type RunProceduralAblationCliArgs, type RunProceduralAblationOptions, type RunSequentialPhasesOptions, SCHEMA_TIER_FIXTURE, SCHEMA_TIER_SMOKE_FIXTURE, SEALED_PROMPT_REGISTRY, SYNTHETIC_MEMORIES, type SanitizedDiagnosticProvider, type SavedBaseline, type SchemaTierCorpus, type SchemaTierFixture, type SchemaTierName, type SchemaTierPage, type SchemaTierPageFrontmatter, type SealedArtifact, type SealedJudgeDecision, type SealedJudgeInput, type SealedQrelsArtifact, type SealedQrelsHandle, type SealedRubric, type SearchResult, type SeededMemory, type SeededRng, type SequentialPhaseHooks, type SpotCheckLogger, type StatisticalReport, type StructuredJudge, type SyntheticEmailIngestionAdapterOptions, type SyntheticTargetOptions, type TaskResult, type TaskTokenUsage, type TemporalRetrievalCase, type TierDetail, type TimelineEntry, type TokenUsage, type WriteBenchmarkArtifactResult, addContaminationEntry, aggregateTaskScores, answerBenchmarkQuestion, assertCanaryUnderFloor, assertIntegrityMetaPresent, assertPublishableIntegrity, assertSha256Hex, assistantMeetingPrepDefinition, assistantMorningBriefDefinition, assistantNextBestActionDefinition, assistantSynthesisDefinition, backlinkF1, binarizeJudgeScore, bootstrapMeanConfidenceInterval, buildAmaBenchDiagnosticMatrixArtifact, buildAmaBenchDiagnosticVariantSummary, buildAmaBenchLeaderboardRows, buildBenchmarkArtifact, buildBenchmarkArtifactFilename, buildBenchmarkPublishFeed, buildBenchmarkReproManifest, buildBenchmarkRunSeeds, buildJudgePayload, buildOracleTrajectoryRecall, buildSchemaTierFixture, buildSchemaTierSmokeFixture, calendarFixture, canonicalJsonStringify, chatFixture, checkDatasetContamination, checkRegression, clampScore, cohensD, compareResults, computeCohensKappa, computeSealHash, containsAnswer, createSeededRng as createAdamSeededRng, createAmaBenchDiagnosticAdapter, createAnthropicProvider, createCanaryAdapter, createCodexCliProvider, createDeterministicSpotCheckLogger, createGatewayResponder, createLightweightAdapter, createLiteLlmProvider, createLocalLlmProvider, createMitigatedTarget, createOllamaProvider, createOpenAiCompatibleProvider, createSeededRandom as createProceduralAblationSeededRandom, createProvider, createProviderBackedAmaBenchRecommendedJudge, createProviderBackedJudge, createProviderBackedResponder, createProviderBackedStructuredJudge, createRemnicAdapter, createResponderFromProvider, createSeededRng$1 as createSeededRng, createSpotCheckFileLogger, createStructuredJudgeFromProvider, createSyntheticEmailIngestionAdapter, createSyntheticTarget, createTimeoutGuardedAdapter, defaultBenchmarkBaselineDir, defaultBenchmarkPublishPath, deleteBenchmarkResults, discoverAllProviders, discoveryEndpointFor, emailFixture, entityRecall, exactMatch, extractMarkdownSectionsByTitle, f1Score, fixtureToAblationScenarios, formatHandoffNote, formatMissingDatasetError, generateReport, getBenchmark, getBenchmarkLowerIsBetter, getMemoryEvalDimension, getRemnicVersion, hashBenchmarkArtifact, hashBytes, hashCanonicalJson, hashString, integrityMetaIsComplete, interpretEffectSize, isAmaBenchUnknownLikeAnswer, isContaminationEntry, isContaminationManifest, isSealedQrelsArtifact, isSha256Hex, linkMatches, listBenchmarkBaselines, listBenchmarkResults, listBenchmarks, listMemoryEvalBenchmarkIds, listMemoryEvalDimensions, llmJudgeScore, llmJudgeScoreDetailed, loadAblationFixture, loadBaseline, loadBeamDatasetPreview, loadBenchmarkArtifact, loadBenchmarkBaseline, loadBenchmarkResult, loadCustomBenchmarkFile, loadJudgeCalibrationState, loadLoCoMo10, loadLocalLabManifest, loadLongMemEvalS, loadSealKeyFromEnv, loadSealedQrels, loadSealedRubric, matchEntity, mergeContaminationManifests, openSeal, orchestrateBenchmarkRuns, pairedDeltaConfidenceInterval, parseBenchmarkArtifact, parseCustomBenchmark, parseLocalLabManifest, parseRubricResponse, parseSealedQrels, precisionAtK, preflightLocalLabRole, projectFolderFixture, recallAtK, redactBenchmarkResultSecrets, renderBaselineMarkdown, renderBenchmarkResultExport, renderMemorySummaryForJudge, renderMemoryViewForAgent, resolveAssistantAgent, resolveAssistantRubricId, resolveAssistantSeeds, resolveAssistantSpotCheckDir, resolveBenchRuntimeProfile, resolveBenchmarkPhaseTimeoutMs, resolveBenchmarkProgressLogging, resolveBenchmarkResultReference, resolveBenchmarkRunCount, resolveLocalLabProfile, resolveLocalLabRole, resolveStructuredJudge, rotateDistractors, rougeL, runAssistantBenchmark, runAssistantMeetingPrepBenchmark, runAssistantMorningBriefBenchmark, runAssistantNextBestActionBenchmark, runAssistantSynthesisBenchmark, runBaseline, runBenchSuite, runBenchmark, runCustomBenchmarkFile, runExplain, runExtractionAttack, runJudgeCalibration, runMitigatedBaseline, runProceduralAblation, runProceduralAblationCli, runSealedJudge, runSequentialPhases, safeHexEqual, saveBaseline, saveBenchmarkBaseline, schemaCompleteness, sealPayload, selectAmaBenchDiagnosticVariants, selectCalibrationSlice, selectFixtureVariant, serializeBenchmarkArtifact, serializeJsonl, serializeSealedQrels, shuffleTasks, timed, verifyRubricDigest, writeBenchmarkArtifact, writeBenchmarkPublishFeed, writeBenchmarkReproManifest, writeBenchmarkResult, writeJudgeCalibrationState, writeLeaderboardArtifactsForResult, zeroScores };
+/**
+ * Coding-graph benchmark types (issue #1557).
+ *
+ * These types define the metric report shape, the benchmark configuration,
+ * and the regression-gate contract. The harness writes a {@link CodingGraphBenchReport};
+ * the regression step compares it against a tracked {@link CodingGraphBaseline}.
+ *
+ * Design rules (from the issue):
+ *   - Metrics are recorded as a tracked baseline (same philosophy as
+ *     scripts/ratchet-baseline.json), NOT inline thresholds.
+ *   - The comparison step hard-fails on gross regression (rule 50) with a
+ *     generous tolerance — perf thresholds in CI flake.
+ *   - Every metric that enters the report must have a plausible type so
+ *     the smoke test can assert presence without knowing exact values.
+ *   - The report includes a machine fingerprint so baselines are comparable
+ *     across runs (the issue calls this out explicitly).
+ */
+/**
+ * Parameters for the deterministic synthetic repo generator. Same seed +
+ * same params → byte-identical IR output (rule 38 — generator determinism).
+ */
+interface SyntheticRepoConfig {
+    /** PRNG seed — same seed + params = identical output. */
+    readonly seed: number;
+    /** Number of synthetic source files. */
+    readonly fileCount: number;
+    /** Symbols (functions/classes/methods) per file. */
+    readonly symbolsPerFile: number;
+    /**
+     * Edge density — probability [0,1] that any given symbol calls another.
+     * Higher = denser call graph (more edges per node).
+     */
+    readonly callDensity: number;
+    /** Language tier label (informational — the IR is language-agnostic). */
+    readonly language: string;
+}
+/**
+ * Generated fixture — the IR plus approximate LOC and a structural summary.
+ */
+interface GeneratedRepo {
+    readonly files: readonly SyntheticFileIR[];
+    /** Approximate LOC (symbolsPerFile × fileCount × avgLinesPerSymbol). */
+    readonly approximateLoc: number;
+    readonly config: SyntheticRepoConfig;
+}
+/**
+ * Minimal IR shape for the synthetic generator. Matches the subset of
+ * {@link StoreFileIR} the harness exercises: symbols + CALLS edges. The
+ * generator emits this shape directly so the benchmark measures the STORE,
+ * not the parser (parser benchmarks are a separate concern).
+ */
+interface SyntheticFileIR {
+    readonly path: string;
+    readonly language: string;
+    readonly contentHash: string;
+    readonly symbols: readonly SyntheticSymbol[];
+    readonly edges: readonly SyntheticEdge[];
+}
+interface SyntheticSymbol {
+    readonly qualifiedName: string;
+    readonly name: string;
+    readonly kind: string;
+    readonly startByte: number;
+    readonly endByte: number;
+}
+interface SyntheticEdge {
+    readonly srcQualifiedName: string;
+    readonly dstQualifiedName: string;
+    readonly type: string;
+    readonly confidence: number;
+    readonly provenance: string;
+}
+interface MachineFingerprint {
+    readonly arch: string;
+    readonly platform: string;
+    readonly nodeVersion: string;
+    readonly cpuModel: string | null;
+    readonly cpuCores: number;
+    readonly totalMemoryMb: number;
+}
+/**
+ * Micro-metric result with percentile distribution. `samples` is the raw
+ * array of per-iteration measurements (ms); p50/p95 are computed from it.
+ */
+interface MicroMetric {
+    /** Median (p50) in milliseconds. */
+    readonly p50: number;
+    /** 95th percentile in milliseconds. */
+    readonly p95: number;
+    /** Number of iterations measured. */
+    readonly iterations: number;
+    /** Raw per-iteration timings (ms) — kept so the report is auditable. */
+    readonly samplesMs: readonly number[];
+}
+/** A single wall-clock measurement (ms) with no distribution. */
+interface WallMetric {
+    readonly ms: number;
+    readonly detail?: string;
+}
+/**
+ * All metric keys that the harness can produce. Each is lower-is-better
+ * except `fullIndexLocsPerSecond` (higher is better).
+ *
+ * The regression gate compares only keys present in BOTH the report and
+ * the baseline — new metrics are additive, never blocking.
+ */
+type CodingGraphMetricKey = "fullIndexMs" | "fullIndexLocsPerSecond" | "incrementalUpdateP50Ms" | "incrementalUpdateP95Ms" | "tracePathP95Ms" | "searchGraphP95Ms" | "deadCodeMs" | "dbBytesPerKloc";
+interface CodingGraphBenchReport {
+    /** Schema version — bump when the report shape changes. */
+    readonly schemaVersion: number;
+    readonly timestamp: string;
+    readonly machine: MachineFingerprint;
+    readonly fixture: {
+        readonly config: SyntheticRepoConfig;
+        readonly approximateLoc: number;
+        readonly fileCount: number;
+        readonly symbolCount: number;
+        readonly edgeCount: number;
+    };
+    /** Full-index wall time (ms) for the entire fixture. */
+    readonly fullIndexMs: WallMetric;
+    /** LOC/s sustained during full index (higher is better). */
+    readonly fullIndexLocsPerSecond: number;
+    /** Incremental single-file update latency distribution. */
+    readonly incrementalUpdate: MicroMetric;
+    /** trace_path (depth ≤ 5) latency distribution. */
+    readonly tracePath: MicroMetric;
+    /** search_graph name-pattern latency distribution. */
+    readonly searchGraph: MicroMetric;
+    /** Dead-code query wall time (ms). */
+    readonly deadCodeMs: WallMetric;
+    /** DB bytes per KLOC after index. */
+    readonly dbBytesPerKloc: number;
+    /** Peak RSS (bytes) at the end of the run. */
+    readonly peakRssBytes: number;
+    /** DB file size in bytes after index. */
+    readonly dbBytes: number;
+    /** Total node + edge count after index. */
+    readonly graphNodeCount: number;
+    readonly graphEdgeCount: number;
+}
+/**
+ * Tracked baseline JSON (bench-owned, separate file from the structural
+ * ratchets in scripts/ratchet-baseline.json per issue #1557).
+ */
+interface CodingGraphBaseline {
+    readonly schemaVersion: number;
+    readonly machine: MachineFingerprint;
+    readonly fixtureConfig: SyntheticRepoConfig;
+    readonly metrics: Readonly<Record<string, number>>;
+    readonly createdAt: string;
+    /** Human-readable note about how the baseline was captured. */
+    readonly note: string;
+}
+/**
+ * Per-metric regression detail. `direction` encodes whether higher or
+ * lower is better; `regressed` is true when the measured value exceeds
+ * the tolerance-adjusted baseline.
+ */
+interface RegressionMetricDetail {
+    readonly key: string;
+    readonly baseline: number;
+    readonly measured: number;
+    /** Percentage change relative to baseline (positive = worse). */
+    readonly percentChange: number;
+    readonly direction: "lower-is-better" | "higher-is-better";
+    readonly tolerancePercent: number;
+    readonly regressed: boolean;
+}
+interface RegressionGateResult {
+    readonly passed: boolean;
+    readonly regressions: readonly RegressionMetricDetail[];
+    readonly summary: string;
+}
+interface CodingGraphBenchConfig {
+    /** Fixture parameters. Defaults to a small, fast smoke fixture. */
+    readonly fixture?: Partial<SyntheticRepoConfig>;
+    /**
+     * Iterations for micro-metrics (p50/p95). Minimum 20 per the issue.
+     * Default 20.
+     */
+    readonly iterations?: number;
+    /** BFS depth for trace_path measurements. Default 5. */
+    readonly traceDepth?: number;
+    /**
+     * Regression tolerance (percent). A metric must regress by MORE than
+     * this to count as a failure. Default 30 (generous — perf thresholds
+     * in CI flake).
+     */
+    readonly tolerancePercent?: number;
+}
+/** Default fixture — small enough for a sub-second smoke run. */
+declare const DEFAULT_SMOKE_FIXTURE: SyntheticRepoConfig;
+/** Default fixture for a 10k-node scale run (~1k files × 10 symbols). */
+declare const DEFAULT_10K_FIXTURE: SyntheticRepoConfig;
+/** Minimum iterations for percentile metrics (issue #1557: ≥20). */
+declare const MIN_ITERATIONS = 20;
+/** Default regression tolerance (issue #1557: generous, e.g. 30%). */
+declare const DEFAULT_TOLERANCE_PERCENT = 30;
+/** Report schema version — bump when the shape changes. */
+declare const CODING_GRAPH_BENCH_SCHEMA_VERSION = 1;
+
+/**
+ * Deterministic synthetic repo generator (issue #1557 design (a)).
+ *
+ * Produces {@link GeneratedRepo} — a set of synthetic StoreFileIR-shaped
+ * files with symbols and CALLS edges. The generator is parameterized:
+ * files × functions × call-density × language. Same seed + same params
+ * always yields byte-identical output (rule 38 — generator determinism).
+ *
+ * The generator emits IR directly (not source code) because:
+ *   1. The benchmark measures the GRAPH STORE, not the parser. Parser
+ *      benchmarks are a separate concern (the parser has its own test
+ *      suite in packages/coding-graph/src/engine/).
+ *   2. Emitting IR avoids coupling the store benchmark to grammar
+ *      availability, which varies by platform (rule 30).
+ *   3. Synthetic IR is deterministic by construction — no parsing
+ *      nondeterminism can leak into the benchmark.
+ *
+ * Public-repo policy: fixtures are synthetic only. No real source code
+ * is committed or fetched by this generator. Pinned OSS repos are a
+ * separate prepare step (issue step 4 — not this PR).
+ */
+
+/**
+ * Create a deterministic PRNG from a 32-bit seed. Returns a function that
+ * produces floats in [0, 1). Same seed → identical sequence (rule 38).
+ */
+declare function createSeededRng(seed: number): () => number;
+/**
+ * Generate a deterministic synthetic repo from the given config.
+ *
+ * Determinism guarantee (rule 38): calling this function twice with the
+ * same {@link SyntheticRepoConfig} produces structurally identical output
+ * — same files, same symbols, same edges, same byte spans, same hashes.
+ */
+declare function generateSyntheticRepo(config: SyntheticRepoConfig): GeneratedRepo;
+/**
+ * Pick a random qualified name from the repo for query benchmarking.
+ * Deterministic given the same seed (so trace/search benchmarks use a
+ * stable start node across runs).
+ */
+declare function pickStableQualifiedName(repo: GeneratedRepo, index: number): string;
+
+/**
+ * Coding-graph benchmark harness (issue #1557).
+ *
+ * Runs the full metric set against a synthetic fixture and produces a
+ * {@link CodingGraphBenchReport}. The harness is the authority for
+ * performance claims — no number ships in docs without a harness
+ * measurement behind it (rule 55).
+ *
+ * Metrics measured (per the issue):
+ *   - full-index wall time + LOC/s
+ *   - incremental single-file update latency p50/p95
+ *   - trace_path (depth ≤ 5) p95
+ *   - search_graph name-pattern p95
+ *   - dead-code query wall time
+ *   - DB bytes per KLOC
+ *   - peak RSS
+ *
+ * Timing uses `performance.now()` (monotonic). p95 computed over ≥20
+ * iterations for micro metrics. The report includes a machine fingerprint
+ * so baselines are comparable.
+ */
+
+declare function captureMachineFingerprint(): MachineFingerprint;
+/**
+ * Run the coding-graph benchmark suite against a synthetic fixture.
+ *
+ * Produces a {@link CodingGraphBenchReport} with every metric key. The
+ * report is fully JSON-serializable so it can be written to disk, compared
+ * against a baseline, or embedded in docs.
+ *
+ * @param config Run configuration. Defaults to a small smoke fixture.
+ */
+declare function runCodingGraphBenchmark(config?: CodingGraphBenchConfig): Promise<CodingGraphBenchReport>;
+
+/**
+ * Coding-graph regression gate (issue #1557 step 3).
+ *
+ * Compares a benchmark report against a tracked baseline with a generous
+ * tolerance. Hard-fails on gross regression — a real failing step, not a
+ * warning (rule 50: no `|| true`). Tightening the baseline is a deliberate
+ * PR act, mirroring `check-ratchets --update` (rule 50).
+ *
+ * The baseline is bench-owned (separate file from the structural ratchets
+ * in scripts/ratchet-baseline.json). New metrics are additive: only keys
+ * present in BOTH the report and the baseline are compared.
+ */
+
+declare const METRIC_DIRECTION: {
+    fullIndexMs: "lower-is-better";
+    fullIndexLocsPerSecond: "higher-is-better";
+    incrementalUpdateP95Ms: "lower-is-better";
+    incrementalUpdateP50Ms: "lower-is-better";
+    tracePathP95Ms: "lower-is-better";
+    searchGraphP95Ms: "lower-is-better";
+    deadCodeMs: "lower-is-better";
+    dbBytesPerKloc: "lower-is-better";
+};
+type RegressionMetricKey = keyof typeof METRIC_DIRECTION;
+/**
+ * Extract the flat metric map from a report for comparison.
+ */
+declare function extractMetrics(report: CodingGraphBenchReport): Record<string, number>;
+/**
+ * Compare a report against a baseline. Returns a gate result that exits
+ * non-zero when any metric regresses beyond the tolerance.
+ *
+ * @param report The current run's metrics.
+ * @param baseline The tracked baseline to compare against.
+ * @param tolerancePercent How much worse a metric can be before it counts
+ *   as a regression. Default 30 (generous — perf in CI flake).
+ */
+declare function checkCodingGraphRegression(report: CodingGraphBenchReport, baseline: CodingGraphBaseline, tolerancePercent?: number): RegressionGateResult;
+/**
+ * Build a baseline object from a report, suitable for writing to the
+ * tracked baseline JSON file. This is the "deliberate PR act" that
+ * tightens the baseline (mirrors `check-ratchets --update`).
+ */
+declare function buildBaselineFromReport(report: CodingGraphBenchReport, note: string): CodingGraphBaseline;
+
+export { AMA_BENCH_DIAGNOSTIC_VARIANTS, ASSISTANT_AGENT_CONFIG_KEY, ASSISTANT_JUDGE_CONFIG_KEY, ASSISTANT_MEETING_PREP_SCENARIOS, ASSISTANT_MEETING_PREP_SMOKE_SCENARIOS, ASSISTANT_MORNING_BRIEF_SCENARIOS, ASSISTANT_MORNING_BRIEF_SMOKE_SCENARIOS, ASSISTANT_NEXT_BEST_ACTION_SCENARIOS, ASSISTANT_NEXT_BEST_ACTION_SMOKE_SCENARIOS, ASSISTANT_RUBRIC_DIMENSIONS, ASSISTANT_RUBRIC_ID_KEY, ASSISTANT_SEEDS_CONFIG_KEY, ASSISTANT_SPOT_CHECK_DIR_KEY, ASSISTANT_SYNTHESIS_SCENARIOS, ASSISTANT_SYNTHESIS_SMOKE_SCENARIOS, type AbstentionRetrievalCase, type AggregateMetrics, type AmaBenchDiagnosticAdapterOptions, type AmaBenchDiagnosticAnswererMode, type AmaBenchDiagnosticBreakdown, type AmaBenchDiagnosticMatrixArtifact, type AmaBenchDiagnosticRecallMode, type AmaBenchDiagnosticRunContext, type AmaBenchDiagnosticTaskEvidence, type AmaBenchDiagnosticTaskRow, type AmaBenchDiagnosticVariant, type AmaBenchDiagnosticVariantSummary, type AnthropicProviderConfig, type AssistantAgent, type AssistantMemoryFact, type AssistantMemoryGraph, type AssistantRubricDimension, type AssistantRubricScores, type AssistantRunnerOptions, type AssistantScenario, type AssistantStance, type AttackRecallOptions, type AttackRetrievalHit, type AttackerMode, BENCHMARK_ARTIFACT_SCHEMA_VERSION, BENCHMARK_INTEGRITY_META_SCHEMA, BENCHMARK_REPRO_MANIFEST_FILENAME, BENCHMARK_REPRO_MANIFEST_SCHEMA_VERSION, BENCHMARK_RESULT_SCHEMA, BENCHMARK_SPLIT_TYPES, type BaselineRow, type BaselineScenario, type BeamDatasetPreview, type BenchConfig, type BenchJudge, type BenchJudgeResult, type BenchMemoryAdapter, type BenchModelSource, type BenchReasoningEffort, type BenchRecallOptions, type BenchResponder, type BenchResponse, type BenchRuntimeProfile, type BenchTier, type BenchmarkArtifact, type BenchmarkArtifactEnvironment, type BenchmarkArtifactHardware, type BenchmarkArtifactJudgeCalibration, type BenchmarkArtifactPerTaskScore, type BenchmarkArtifactSystem, type BenchmarkArtifactTier, type BenchmarkCategory, type BenchmarkDefinition, type BenchmarkIntegrityMeta, type BenchmarkMeta, type BenchmarkMode, type BenchmarkReport, type BenchmarkReproManifest, type BenchmarkReproManifestDataset, type BenchmarkReproManifestFile, type BenchmarkReproManifestResult, type BenchmarkResult, type BenchmarkSplitType, type BenchmarkStatus, type BenchmarkSuiteResult, type BenchmarkTier, type BuildBenchmarkArtifactInput, type BuildBenchmarkPublishFeedOptions, type BuildBenchmarkReproManifestOptions, type BuiltInProvider, CALIBRATION_SLICE_SIZE, CANARY_FIXED_RECALL, CANARY_SCORE_FLOOR, DEFAULT_10K_FIXTURE as CODING_GRAPH_10K_FIXTURE, CODING_GRAPH_BENCH_SCHEMA_VERSION, DEFAULT_TOLERANCE_PERCENT as CODING_GRAPH_DEFAULT_TOLERANCE, MIN_ITERATIONS as CODING_GRAPH_MIN_ITERATIONS, DEFAULT_SMOKE_FIXTURE as CODING_GRAPH_SMOKE_FIXTURE, type CalibrationAnswer, type CalibrationVerdictPair, type CanaryAdapterOptions, type CanaryFloorCheck, type CodexCliProviderConfig, type CodingGraphBaseline, type CodingGraphBenchConfig, type CodingGraphBenchReport, type MachineFingerprint as CodingGraphMachineFingerprint, type CodingGraphMetricKey, type RegressionMetricDetail as CodingGraphRegressionDetail, type RegressionMetricKey as CodingGraphRegressionKey, type RegressionGateResult as CodingGraphRegressionResult, type CohenKappaResult, type ComparisonMetricDelta, type ComparisonResult, type CompletionOpts, type CompletionResult, type ConfidenceInterval, type ContaminationCheckResult, type ContaminationEntry, type ContaminationManifest, type CustomBenchmarkScoring, type CustomBenchmarkSpec, type CustomBenchmarkTask, DEFAULT_ABLATION_BOOTSTRAP_SEED, DEFAULT_ASSISTANT_RUBRIC_ID, DEFAULT_BASELINE_SCENARIOS, DEFAULT_JUDGE_BINARIZATION_THRESHOLD, type DatasetSource, type DiscoveredModel, EMPTY_CONTAMINATION_MANIFEST, type EffectSizeInterpretation, type EffectSizeSummary, type ExplainResult, type ExtractedEntity, type ExtractedLink, type ExtractedPage, type ExtractionAttackOptions, type ExtractionAttackResult, type ExtractionAttackTarget, type FixtureGenerator, type FixtureOutput, type FixtureVariant, type GeneratedFile, type GeneratedRepo, type GoldEntity, type GoldEntityType, type GoldGraph, type GoldLink, type GoldPage, type HarnessRng, INTEGRITY_CIPHER_ALGORITHM, INTEGRITY_HASH_ALGORITHM, INTEGRITY_META_FIELDS, type IngestionBenchAdapter, type IngestionLog, JUDGE_CALIBRATION_KAPPA_THRESHOLD, type JudgeCalibrationIdentities, type JudgeCalibrationResult, type JudgeCategory, LOCAL_LAB_PROVIDER_KINDS, LOCOMO_DATASET_FILENAMES, LONG_MEM_EVAL_DATASET_FILENAMES, type LeaderboardArtifactWrite, type LlmJudge, type LlmProvider, type LoadDatasetOptions, type LoadSealedQrelsOptions, type LoadedDataset, type LoadedJudgeCalibrationState, type LocalLabManifest, type LocalLabManifestNotes, type LocalLabPhase, type LocalLabPhaseDescriptor, type LocalLabPhaseExecute, type LocalLabPhaseName, type LocalLabPhaseOutcome, LocalLabPreflightError, type LocalLabPreflightFailure, type LocalLabPreflightInput, type LocalLabPreflightOptions, type LocalLabPreflightResult, type LocalLabPreflightSuccess, type LocalLabProviderKind, type LocalLabRoleConfig, type LocalLlmProviderConfig, MEMORY_EVAL_DIMENSIONS, MEMORY_EVAL_PUBLIC_LINE, MIN_CALIBRATION_SOURCE_TASKS, MITIGATED_BASELINE_SCENARIOS, type MemCorrectGeneratorOptions, type MemCorrectSystemAdapter, type MemoryEvalCategory, type MemoryEvalDimension, type MemoryEvalDimensionId, type MemoryEvalMetric, type MemoryGraph, type MemoryStats, type MemorySystem, type Message, type MetricAggregate, type MicroMetric, type MitigatedBaselineConfig, type MitigatedTargetConfig, type MultipleChoiceQuestion, OTHER_NAMESPACE_MEMORIES, type OllamaProviderConfig, type OpenAiCompatibleProviderConfig, PROCEDURAL_REAL_SCENARIOS, PROCEDURAL_REAL_SCENARIOS_SMOKE, PUBLISHED_BENCHMARK_ARTIFACT_IDS, type PersonalizationRetrievalCase, type PreflightDiscoveredModel, type ProceduralAblationArtifact, type ProceduralAblationPerCase, type ProceduralAblationScenario, type ProceduralRealScenario, type ProceduralRealScenarioCategory, type ProviderBaseConfig, type ProviderConfig, type ProviderDiscoveryResult, type ProviderFactoryConfig, type PublishSkipReason, type PublishSkipRecord, type PublishedBenchmarkFeed, type PublishedBenchmarkFeedEntry, type PublishedBenchmarkId, REQUIRED_FRONTMATTER_FIELDS, type RecallMetrics, type RecoveredMemory, type RegressionDetail, type RegressionGateResult$1 as RegressionGateResult, type RemnicAdapterOptions, type ResolveBenchRuntimeProfileOptions, type ResolvedBenchRuntimeProfile, type ResolvedLocalLabProfile, type ResolvedLocalLabRole, type ResolvedRunBenchmarkOptions, type RotatedChoices, type RunBenchmarkOptions, type RunJudgeCalibrationOptions, type RunProceduralAblationCliArgs, type RunProceduralAblationOptions, type RunSequentialPhasesOptions, SCHEMA_TIER_FIXTURE, SCHEMA_TIER_SMOKE_FIXTURE, SEALED_PROMPT_REGISTRY, SYNTHETIC_MEMORIES, type SanitizedDiagnosticProvider, type SavedBaseline, type SchemaTierCorpus, type SchemaTierFixture, type SchemaTierName, type SchemaTierPage, type SchemaTierPageFrontmatter, type SealedArtifact, type SealedJudgeDecision, type SealedJudgeInput, type SealedQrelsArtifact, type SealedQrelsHandle, type SealedRubric, type SearchResult, type SeededMemory, type SeededRng, type SequentialPhaseHooks, type SpotCheckLogger, type StatisticalReport, type StructuredJudge, type SyntheticEdge, type SyntheticEmailIngestionAdapterOptions, type SyntheticFileIR, type SyntheticRepoConfig, type SyntheticSymbol, type SyntheticTargetOptions, type TaskResult, type TaskTokenUsage, type TemporalRetrievalCase, type TierDetail, type TimelineEntry, type TokenUsage, type WallMetric, type WriteBenchmarkArtifactResult, addContaminationEntry, aggregateTaskScores, answerBenchmarkQuestion, assertCanaryUnderFloor, assertIntegrityMetaPresent, assertPublishableIntegrity, assertSha256Hex, assistantMeetingPrepDefinition, assistantMorningBriefDefinition, assistantNextBestActionDefinition, assistantSynthesisDefinition, backlinkF1, binarizeJudgeScore, bootstrapMeanConfidenceInterval, buildAmaBenchDiagnosticMatrixArtifact, buildAmaBenchDiagnosticVariantSummary, buildAmaBenchLeaderboardRows, buildBaselineFromReport, buildBenchmarkArtifact, buildBenchmarkArtifactFilename, buildBenchmarkPublishFeed, buildBenchmarkReproManifest, buildBenchmarkRunSeeds, buildJudgePayload, buildOracleTrajectoryRecall, buildSchemaTierFixture, buildSchemaTierSmokeFixture, calendarFixture, canonicalJsonStringify, captureMachineFingerprint, chatFixture, checkCodingGraphRegression, checkDatasetContamination, checkRegression, clampScore, cohensD, compareResults, computeCohensKappa, computeSealHash, containsAnswer, createSeededRng$1 as createAdamSeededRng, createAmaBenchDiagnosticAdapter, createAnthropicProvider, createCanaryAdapter, createCodexCliProvider, createSeededRng as createCodingGraphSeededRng, createDeterministicSpotCheckLogger, createGatewayResponder, createLightweightAdapter, createLiteLlmProvider, createLocalLlmProvider, createMitigatedTarget, createOllamaProvider, createOpenAiCompatibleProvider, createSeededRandom as createProceduralAblationSeededRandom, createProvider, createProviderBackedAmaBenchRecommendedJudge, createProviderBackedJudge, createProviderBackedResponder, createProviderBackedStructuredJudge, createRemnicAdapter, createResponderFromProvider, createSeededRng$2 as createSeededRng, createSpotCheckFileLogger, createStructuredJudgeFromProvider, createSyntheticEmailIngestionAdapter, createSyntheticTarget, createTimeoutGuardedAdapter, defaultBenchmarkBaselineDir, defaultBenchmarkPublishPath, deleteBenchmarkResults, discoverAllProviders, discoveryEndpointFor, emailFixture, entityRecall, exactMatch, extractMetrics as extractCodingGraphMetrics, extractMarkdownSectionsByTitle, f1Score, fixtureToAblationScenarios, formatHandoffNote, formatMissingDatasetError, generateReport, generateSyntheticRepo, getBenchmark, getBenchmarkLowerIsBetter, getMemoryEvalDimension, getRemnicVersion, hashBenchmarkArtifact, hashBytes, hashCanonicalJson, hashString, integrityMetaIsComplete, interpretEffectSize, isAmaBenchUnknownLikeAnswer, isContaminationEntry, isContaminationManifest, isSealedQrelsArtifact, isSha256Hex, linkMatches, listBenchmarkBaselines, listBenchmarkResults, listBenchmarks, listMemoryEvalBenchmarkIds, listMemoryEvalDimensions, llmJudgeScore, llmJudgeScoreDetailed, loadAblationFixture, loadBaseline, loadBeamDatasetPreview, loadBenchmarkArtifact, loadBenchmarkBaseline, loadBenchmarkResult, loadCustomBenchmarkFile, loadJudgeCalibrationState, loadLoCoMo10, loadLocalLabManifest, loadLongMemEvalS, loadSealKeyFromEnv, loadSealedQrels, loadSealedRubric, matchEntity, mergeContaminationManifests, openSeal, orchestrateBenchmarkRuns, pairedDeltaConfidenceInterval, parseBenchmarkArtifact, parseCustomBenchmark, parseLocalLabManifest, parseRubricResponse, parseSealedQrels, pickStableQualifiedName, precisionAtK, preflightLocalLabRole, projectFolderFixture, recallAtK, redactBenchmarkResultSecrets, renderBaselineMarkdown, renderBenchmarkResultExport, renderMemorySummaryForJudge, renderMemoryViewForAgent, resolveAssistantAgent, resolveAssistantRubricId, resolveAssistantSeeds, resolveAssistantSpotCheckDir, resolveBenchRuntimeProfile, resolveBenchmarkPhaseTimeoutMs, resolveBenchmarkProgressLogging, resolveBenchmarkResultReference, resolveBenchmarkRunCount, resolveLocalLabProfile, resolveLocalLabRole, resolveStructuredJudge, rotateDistractors, rougeL, runAssistantBenchmark, runAssistantMeetingPrepBenchmark, runAssistantMorningBriefBenchmark, runAssistantNextBestActionBenchmark, runAssistantSynthesisBenchmark, runBaseline, runBenchSuite, runBenchmark, runCodingGraphBenchmark, runCustomBenchmarkFile, runExplain, runExtractionAttack, runJudgeCalibration, runMitigatedBaseline, runProceduralAblation, runProceduralAblationCli, runSealedJudge, runSequentialPhases, safeHexEqual, saveBaseline, saveBenchmarkBaseline, schemaCompleteness, sealPayload, selectAmaBenchDiagnosticVariants, selectCalibrationSlice, selectFixtureVariant, serializeBenchmarkArtifact, serializeJsonl, serializeSealedQrels, shuffleTasks, timed, verifyRubricDigest, writeBenchmarkArtifact, writeBenchmarkPublishFeed, writeBenchmarkReproManifest, writeBenchmarkResult, writeJudgeCalibrationState, writeLeaderboardArtifactsForResult, zeroScores };

package/dist/index.js

@@ -34709,6 +34709,414 @@ function createMitigatedTarget(config) {
     listEntities: target.listEntities ? async () => target.listEntities() : void 0
   };
 }
+
+// src/coding-graph/generator.ts
+import { createHash as createHash12 } from "crypto";
+function createSeededRng3(seed) {
+  let state = seed >>> 0;
+  return function rng() {
+    state |= 0;
+    state = state + 1831565813 | 0;
+    let t = Math.imul(state ^ state >>> 15, 1 | state);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+var SYMBOL_KINDS = [
+  "function",
+  "function",
+  "function",
+  "method",
+  "method",
+  "class",
+  "interface",
+  "type"
+];
+var EDGE_TYPE_WEIGHTS = [
+  ["CALLS", 0.7],
+  ["USES_TYPE", 0.2],
+  ["IMPLEMENTS", 0.1]
+];
+var PROVENANCE_VALUES = ["heuristic", "heuristic", "heuristic", "trace"];
+var AVG_BYTES_PER_LINE = 40;
+function hashContent(input) {
+  return createHash12("sha256").update(input).digest("hex").slice(0, 16);
+}
+function generateSyntheticRepo(config) {
+  const rng = createSeededRng3(config.seed);
+  const files = [];
+  const edgesByFile = [];
+  let totalLoc = 0;
+  const allSymbols = [];
+  for (let f = 0; f < config.fileCount; f++) {
+    const filePath = `src/module_${f}/index.ts`;
+    const symbols = [];
+    let byteCursor = 0;
+    for (let s = 0; s < config.symbolsPerFile; s++) {
+      const kind = SYMBOL_KINDS[Math.floor(rng() * SYMBOL_KINDS.length)];
+      const name = `${kind}_${f}_${s}`;
+      const qualifiedName = `module_${f}.${name}`;
+      const spanLines = 5 + Math.floor(rng() * 11);
+      const spanBytes = spanLines * AVG_BYTES_PER_LINE;
+      const startByte = byteCursor;
+      const endByte = byteCursor + spanBytes;
+      byteCursor = endByte;
+      symbols.push({
+        qualifiedName,
+        name,
+        kind,
+        startByte,
+        endByte
+      });
+      allSymbols.push({ fileIndex: f, qualifiedName, name, kind });
+    }
+    totalLoc += Math.ceil(byteCursor / AVG_BYTES_PER_LINE);
+    const fileEdges = [];
+    edgesByFile.push(fileEdges);
+    files.push({
+      path: filePath,
+      language: config.language,
+      contentHash: hashContent(`file_${f}_${config.seed}`),
+      symbols,
+      edges: fileEdges
+      // filled in phase 2
+    });
+  }
+  let edgeCount = 0;
+  for (let i = 0; i < allSymbols.length; i++) {
+    const src = allSymbols[i];
+    const edgeRolls = Math.ceil(config.callDensity * 3);
+    for (let e = 0; e < edgeRolls; e++) {
+      if (rng() > config.callDensity) continue;
+      const targetIdx = Math.floor(rng() * allSymbols.length);
+      if (targetIdx === i) continue;
+      const dst = allSymbols[targetIdx];
+      const edgeType = weightedPick(EDGE_TYPE_WEIGHTS, rng);
+      const confidence = 0.5 + rng() * 0.5;
+      const provenance = PROVENANCE_VALUES[Math.floor(rng() * PROVENANCE_VALUES.length)];
+      const edge = {
+        srcQualifiedName: src.qualifiedName,
+        dstQualifiedName: dst.qualifiedName,
+        type: edgeType,
+        confidence,
+        provenance
+      };
+      edgesByFile[src.fileIndex].push(edge);
+      edgeCount++;
+    }
+  }
+  return {
+    files,
+    approximateLoc: totalLoc,
+    config
+  };
+}
+function weightedPick(weights, rng) {
+  const total = weights.reduce((sum, [, w]) => sum + w, 0);
+  let roll = rng() * total;
+  for (const [value, w] of weights) {
+    roll -= w;
+    if (roll <= 0) return value;
+  }
+  return weights[weights.length - 1][0];
+}
+function pickStableQualifiedName(repo, index) {
+  const allNames = [];
+  for (const file of repo.files) {
+    for (const sym of file.symbols) {
+      allNames.push(sym.qualifiedName);
+    }
+  }
+  if (allNames.length === 0) {
+    throw new Error("generateSyntheticRepo: no symbols generated");
+  }
+  return allNames[index % allNames.length];
+}
+
+// src/coding-graph/harness.ts
+import { performance as performance2 } from "perf_hooks";
+import { mkdtemp as mkdtemp12, rm as rm14 } from "fs/promises";
+import { statSync } from "fs";
+import { tmpdir as tmpdir7 } from "os";
+import path36 from "path";
+import os10 from "os";
+import {
+  GraphStore
+} from "@remnic/coding-graph";
+
+// src/coding-graph/types.ts
+var DEFAULT_SMOKE_FIXTURE = {
+  seed: 42,
+  fileCount: 20,
+  symbolsPerFile: 10,
+  callDensity: 0.3,
+  language: "typescript"
+};
+var DEFAULT_10K_FIXTURE = {
+  seed: 42,
+  fileCount: 1e3,
+  symbolsPerFile: 10,
+  callDensity: 0.2,
+  language: "typescript"
+};
+var MIN_ITERATIONS = 20;
+var DEFAULT_TOLERANCE_PERCENT = 30;
+var CODING_GRAPH_BENCH_SCHEMA_VERSION = 1;
+
+// src/coding-graph/harness.ts
+function captureMachineFingerprint() {
+  const cpus = os10.cpus();
+  return {
+    arch: process.arch,
+    platform: process.platform,
+    nodeVersion: process.version,
+    cpuModel: cpus.length > 0 ? cpus[0].model : null,
+    cpuCores: cpus.length,
+    totalMemoryMb: Math.round(os10.totalmem() / (1024 * 1024))
+  };
+}
+function percentile2(sorted, p) {
+  if (sorted.length === 0) return 0;
+  if (sorted.length === 1) return sorted[0];
+  const idx = Math.ceil(p / 100 * sorted.length) - 1;
+  return sorted[Math.max(0, idx)];
+}
+function computeMicroMetric(samplesMs) {
+  const sorted = [...samplesMs].sort((a, b) => a - b);
+  return {
+    p50: percentile2(sorted, 50),
+    p95: percentile2(sorted, 95),
+    iterations: samplesMs.length,
+    samplesMs
+  };
+}
+function toStoreFiles(repo) {
+  return repo.files.map((f) => ({
+    path: f.path,
+    language: f.language,
+    contentHash: f.contentHash,
+    symbols: f.symbols.map((s) => ({
+      qualifiedName: s.qualifiedName,
+      name: s.name,
+      kind: s.kind,
+      span: { startByte: s.startByte, endByte: s.endByte }
+    })),
+    edges: f.edges.map(
+      (e) => ({
+        srcQualifiedName: e.srcQualifiedName,
+        dstQualifiedName: e.dstQualifiedName,
+        type: e.type,
+        confidence: e.confidence,
+        provenance: e.provenance
+      })
+    )
+  }));
+}
+async function timeAsync(fn) {
+  const start = performance2.now();
+  const result = await fn();
+  return { ms: performance2.now() - start, result };
+}
+function timeSync(fn) {
+  const start = performance2.now();
+  const result = fn();
+  return { ms: performance2.now() - start, result };
+}
+async function runCodingGraphBenchmark(config = {}) {
+  const fixtureConfig = {
+    ...DEFAULT_SMOKE_FIXTURE,
+    ...config.fixture
+  };
+  const iterations = Math.max(MIN_ITERATIONS, config.iterations ?? MIN_ITERATIONS);
+  const traceDepth = config.traceDepth ?? 5;
+  const repo = generateSyntheticRepo(fixtureConfig);
+  const storeFiles = toStoreFiles(repo);
+  let peakRss = 0;
+  const sampleRss = () => {
+    peakRss = Math.max(peakRss, process.memoryUsage().rss);
+  };
+  const dir = await mkdtemp12(path36.join(tmpdir7(), "coding-graph-bench-"));
+  const dbPath = path36.join(dir, "bench.sqlite");
+  try {
+    const store = await GraphStore.open({ dbPath });
+    try {
+      const fullIndex = await timeAsync(() => store.upsertFileBatch(storeFiles));
+      if (!fullIndex.result.ok) {
+        throw new Error(`full-index failed: ${fullIndex.result.code}`);
+      }
+      const locsPerSecond = fullIndex.ms > 0 ? repo.approximateLoc / (fullIndex.ms / 1e3) : 0;
+      sampleRss();
+      const stats = store.schemaStats();
+      const graphNodeCount = stats.ok ? stats.stats.nodes : 0;
+      const graphEdgeCount = stats.ok ? stats.stats.edges : 0;
+      const incrementalSamples = [];
+      for (let i = 0; i < iterations; i++) {
+        const fileIdx = i % storeFiles.length;
+        const incResult = await timeAsync(
+          () => store.upsertFileBatch([storeFiles[fileIdx]])
+        );
+        if (!incResult.result.ok) {
+          throw new Error(`incremental update failed: ${incResult.result.code}`);
+        }
+        incrementalSamples.push(incResult.ms);
+      }
+      const startName = repo.files[0]?.symbols[0]?.qualifiedName;
+      const traceSamples = [];
+      if (startName) {
+        for (let i = 0; i < iterations; i++) {
+          const traceRes = timeSync(
+            () => store.traverse({
+              start: startName,
+              maxDepth: traceDepth,
+              direction: "outgoing"
+            })
+          );
+          if (!traceRes.result.ok) {
+            throw new Error(
+              `trace_path failed: ${traceRes.result.code}`
+            );
+          }
+          traceSamples.push(traceRes.ms);
+        }
+      }
+      const searchSamples = [];
+      for (let i = 0; i < iterations; i++) {
+        const searchRes = timeSync(
+          () => store.searchGraph({
+            namePattern: "%function%",
+            limit: 50
+          })
+        );
+        if (!searchRes.result.ok) {
+          throw new Error(
+            `search_graph failed: ${searchRes.result.code}`
+          );
+        }
+        searchSamples.push(searchRes.ms);
+      }
+      const deadCode = timeSync(() => store.deadCode());
+      if (!deadCode.result.ok) {
+        throw new Error(`dead_code failed: ${deadCode.result.code}`);
+      }
+      await store.drain();
+      let dbBytes = statSync(dbPath).size;
+      try {
+        dbBytes += statSync(dbPath + "-wal").size;
+      } catch {
+      }
+      const kloc = Math.max(1, repo.approximateLoc / 1e3);
+      const dbBytesPerKloc = dbBytes / kloc;
+      sampleRss();
+      const peakRssBytes = peakRss;
+      return {
+        schemaVersion: CODING_GRAPH_BENCH_SCHEMA_VERSION,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        machine: captureMachineFingerprint(),
+        fixture: {
+          config: fixtureConfig,
+          approximateLoc: repo.approximateLoc,
+          fileCount: repo.files.length,
+          symbolCount: repo.files.reduce((sum, f) => sum + f.symbols.length, 0),
+          edgeCount: repo.files.reduce((sum, f) => sum + f.edges.length, 0)
+        },
+        fullIndexMs: { ms: fullIndex.ms },
+        fullIndexLocsPerSecond: Math.round(locsPerSecond),
+        incrementalUpdate: computeMicroMetric(incrementalSamples),
+        tracePath: computeMicroMetric(traceSamples.length > 0 ? traceSamples : [0]),
+        searchGraph: computeMicroMetric(searchSamples),
+        deadCodeMs: { ms: deadCode.ms },
+        dbBytesPerKloc: Math.round(dbBytesPerKloc),
+        peakRssBytes,
+        dbBytes,
+        graphNodeCount,
+        graphEdgeCount
+      };
+    } finally {
+      await store.close();
+    }
+  } finally {
+    await rm14(dir, { recursive: true, force: true });
+  }
+}
+
+// src/coding-graph/regression.ts
+var METRIC_DIRECTION = {
+  fullIndexMs: "lower-is-better",
+  fullIndexLocsPerSecond: "higher-is-better",
+  incrementalUpdateP95Ms: "lower-is-better",
+  incrementalUpdateP50Ms: "lower-is-better",
+  tracePathP95Ms: "lower-is-better",
+  searchGraphP95Ms: "lower-is-better",
+  deadCodeMs: "lower-is-better",
+  dbBytesPerKloc: "lower-is-better"
+};
+function extractMetrics(report) {
+  return {
+    fullIndexMs: report.fullIndexMs.ms,
+    fullIndexLocsPerSecond: report.fullIndexLocsPerSecond,
+    incrementalUpdateP50Ms: report.incrementalUpdate.p50,
+    incrementalUpdateP95Ms: report.incrementalUpdate.p95,
+    tracePathP95Ms: report.tracePath.p95,
+    searchGraphP95Ms: report.searchGraph.p95,
+    deadCodeMs: report.deadCodeMs.ms,
+    dbBytesPerKloc: report.dbBytesPerKloc
+  };
+}
+function checkCodingGraphRegression(report, baseline, tolerancePercent = DEFAULT_TOLERANCE_PERCENT) {
+  const measured = extractMetrics(report);
+  const baselineMetrics = baseline.metrics;
+  const regressions = [];
+  const reportFixture = report.fixture.config;
+  const baselineFixture = baseline.fixtureConfig;
+  const mismatchedKeys = Object.keys(baselineFixture).filter((key) => reportFixture[key] !== baselineFixture[key]);
+  if (mismatchedKeys.length > 0) {
+    const diffs = mismatchedKeys.map(
+      (key) => `${key}: report=${reportFixture[key]} baseline=${baselineFixture[key]}`
+    ).join(", ");
+    return {
+      passed: false,
+      regressions: [],
+      summary: `Fixture mismatch (${diffs}). Metrics are not comparable across different fixtures.`
+    };
+  }
+  for (const key of Object.keys(METRIC_DIRECTION)) {
+    const baseVal = baselineMetrics[key];
+    const measVal = measured[key];
+    if (baseVal == null || measVal == null) continue;
+    if (baseVal === 0) continue;
+    const direction = METRIC_DIRECTION[key];
+    const ratio2 = measVal / baseVal;
+    const percentChange2 = direction === "lower-is-better" ? (ratio2 - 1) * 100 : (1 - ratio2) * 100;
+    const regressed = percentChange2 > tolerancePercent;
+    if (regressed) {
+      regressions.push({
+        key,
+        baseline: baseVal,
+        measured: measVal,
+        percentChange: Math.round(percentChange2 * 10) / 10,
+        direction,
+        tolerancePercent,
+        regressed: true
+      });
+    }
+  }
+  const passed = regressions.length === 0;
+  const summary = passed ? "All metrics within tolerance." : `${regressions.length} metric(s) regressed beyond ${tolerancePercent}% tolerance:
+` + regressions.map(
+    (r) => `  ${r.key}: ${r.baseline} \u2192 ${r.measured} (${r.percentChange > 0 ? "+" : ""}${r.percentChange}% vs baseline)`
+  ).join("\n");
+  return { passed, regressions, summary };
+}
+function buildBaselineFromReport(report, note) {
+  return {
+    schemaVersion: report.schemaVersion,
+    machine: report.machine,
+    fixtureConfig: report.fixture.config,
+    metrics: extractMetrics(report),
+    createdAt: report.timestamp,
+    note
+  };
+}
 export {
   AMA_BENCH_DIAGNOSTIC_VARIANTS,
   ASSISTANT_AGENT_CONFIG_KEY,
@@ -34734,6 +35142,11 @@ export {
   CALIBRATION_SLICE_SIZE,
   CANARY_FIXED_RECALL,
   CANARY_SCORE_FLOOR,
+  DEFAULT_10K_FIXTURE as CODING_GRAPH_10K_FIXTURE,
+  CODING_GRAPH_BENCH_SCHEMA_VERSION,
+  DEFAULT_TOLERANCE_PERCENT as CODING_GRAPH_DEFAULT_TOLERANCE,
+  MIN_ITERATIONS as CODING_GRAPH_MIN_ITERATIONS,
+  DEFAULT_SMOKE_FIXTURE as CODING_GRAPH_SMOKE_FIXTURE,
   DEFAULT_ABLATION_BOOTSTRAP_SEED,
   DEFAULT_ASSISTANT_RUBRIC_ID,
   DEFAULT_BASELINE_SCENARIOS,
@@ -34777,6 +35190,7 @@ export {
   buildAmaBenchDiagnosticMatrixArtifact,
   buildAmaBenchDiagnosticVariantSummary,
   buildAmaBenchLeaderboardRows,
+  buildBaselineFromReport,
   buildBenchmarkArtifact,
   buildBenchmarkArtifactFilename,
   buildBenchmarkPublishFeed,
@@ -34788,7 +35202,9 @@ export {
   buildSchemaTierSmokeFixture,
   calendarFixture,
   canonicalJsonStringify,
+  captureMachineFingerprint,
   chatFixture,
+  checkCodingGraphRegression,
   checkDatasetContamination,
   checkRegression,
   clampScore,
@@ -34802,6 +35218,7 @@ export {
   createAnthropicProvider,
   createCanaryAdapter,
   createCodexCliProvider,
+  createSeededRng3 as createCodingGraphSeededRng,
   createDeterministicSpotCheckLogger,
   createGatewayResponder,
   createLightweightAdapter,
@@ -34832,12 +35249,14 @@ export {
   emailFixture,
   entityRecall,
   exactMatch,
+  extractMetrics as extractCodingGraphMetrics,
   extractMarkdownSectionsByTitle,
   f1Score,
   fixtureToAblationScenarios,
   formatHandoffNote,
   formatMissingDatasetError,
   generateReport,
+  generateSyntheticRepo,
   getBenchmark,
   getBenchmarkLowerIsBetter,
   getMemoryEvalDimension,
@@ -34885,6 +35304,7 @@ export {
   parseLocalLabManifest,
   parseRubricResponse,
   parseSealedQrels,
+  pickStableQualifiedName,
   precisionAtK,
   preflightLocalLabRole,
   projectFolderFixture,
@@ -34916,6 +35336,7 @@ export {
   runBaseline,
   runBenchSuite,
   runBenchmark,
+  runCodingGraphBenchmark,
   runCustomBenchmarkFile,
   runExplain,
   runExtractionAttack,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/bench",
-  "version": "9.3.710",
+  "version": "9.3.712",
   "description": "Retrieval latency ladder benchmarks + CI regression gates for @remnic/core",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,7 +36,8 @@
   "dependencies": {
     "hyparquet": "^1.25.7",
     "yaml": "^2.4.2",
-    "@remnic/core": "^9.3.710"
+    "@remnic/coding-graph": "^9.3.712",
+    "@remnic/core": "^9.3.712"
   },
   "devDependencies": {
     "tsup": "^8.5.1",