gitnexus 1.6.3-rc.2 → 1.6.3-rc.21

package/dist/core/ingestion/shadow-harness.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Shadow-mode parity harness — dual-run observability for the RFC #909
+ * registry rollout (RFC §6.3; Ring 2 PKG #923).
+ *
+ * ## What it does
+ *
+ *   - Exposes `record({ language, callsite, legacy, newResult })` for
+ *     every call site where the caller has BOTH a legacy-DAG resolution
+ *     and a new `Registry.lookup` resolution.
+ *   - Computes a `ShadowDiff` per record via shared `diffResolutions`
+ *     (#918) and accumulates them in a per-language bucket.
+ *   - At the end of a run, aggregates into a `ShadowParityReport` via
+ *     shared `aggregateDiffs` (#918) — per-language parity %,
+ *     evidence-kind breakdown of divergences, grand-total overall row.
+ *   - Optionally persists the report as JSON under
+ *     `.gitnexus/shadow-parity/` so the static dashboard at
+ *     `gitnexus/shadow-parity-dashboard/` can render it offline.
+ *
+ * ## What it does NOT do
+ *
+ *   - **Invoke either resolution path itself.** The caller must run
+ *     legacy + `Registry.lookup` and pass results in. The harness is a
+ *     side-car, not a dispatcher — this keeps call-processor integration
+ *     surgical when it lands (tracked as a follow-up; the shared model
+ *     doesn't dual-invoke on its own).
+ *   - **Flip anything.** `REGISTRY_PRIMARY_<LANG>` lives in
+ *     `registry-primary-flag.ts` (#924); the harness records the
+ *     caller-supplied "which side is primary" bit for each record so the
+ *     dashboard can label rows, but it does not consult the flag itself.
+ *
+ * ## Activation
+ *
+ * `GITNEXUS_SHADOW_MODE=1` (or `'true'`, `'yes'`, case-insensitive,
+ * trimmed) enables the harness. When disabled, `record()` is a cheap
+ * no-op: no accumulation, no allocation beyond the harness object
+ * itself. Callers can always construct a harness and hand it through;
+ * the "off" overhead is near-zero.
+ *
+ * ## Persistence shape
+ *
+ * When `persist()` is called, the harness writes TWO files:
+ *
+ *   - `<outputDir>/<runId>.json` — the timestamped snapshot (immutable)
+ *   - `<outputDir>/latest.json`  — a pointer that the dashboard reads
+ *
+ * Both files contain the same `PersistedShadowReport` payload:
+ *
+ *   {
+ *     schemaVersion: 1,
+ *     runId: "<iso-8601>-<rand>",
+ *     generatedAt: "<iso-8601>",
+ *     primaryByLanguage: { [lang]: "legacy" | "registry" },
+ *     report: <ShadowParityReport>
+ *   }
+ *
+ * Schema-version-gated so future format changes don't silently confuse
+ * older dashboards. The dashboard renders `report.perLanguage` rows and
+ * annotates each with `primaryByLanguage[lang]`.
+ */
+import { type Resolution, type ShadowCallsite, type ShadowParityReport, type SupportedLanguages } from '../../_shared/index.js';
+/** Which side of the dual-run is considered authoritative for this language. */
+export type PrimarySide = 'legacy' | 'registry';
+/** One record per call site the caller dual-runs. */
+export interface ShadowRecordInput {
+    readonly language: SupportedLanguages;
+    readonly callsite: ShadowCallsite;
+    readonly legacy: readonly Resolution[];
+    readonly newResult: readonly Resolution[];
+    /**
+     * Which side drove the actual runtime answer for this record. Lets the
+     * dashboard distinguish "registry-primary, legacy is shadow" from the
+     * default "legacy-primary, registry is shadow" without re-reading
+     * `REGISTRY_PRIMARY_<LANG>` env vars at render time.
+     */
+    readonly primary: PrimarySide;
+}
+/** Persisted JSON shape. Schema-versioned for future migrations. */
+export interface PersistedShadowReport {
+    readonly schemaVersion: 1;
+    readonly runId: string;
+    readonly generatedAt: string;
+    readonly primaryByLanguage: Readonly<Partial<Record<SupportedLanguages, PrimarySide>>>;
+    readonly report: ShadowParityReport;
+}
+export interface ShadowHarness {
+    /** `true` iff `GITNEXUS_SHADOW_MODE` is truthy. When `false`, `record()` is a no-op. */
+    readonly enabled: boolean;
+    /** Accumulate a dual-run observation. No-op when `enabled === false`. */
+    record(input: ShadowRecordInput): void;
+    /** Number of records accumulated so far. Useful for diagnostics / tests. */
+    size(): number;
+    /**
+     * Aggregate the accumulated records into a `ShadowParityReport`
+     * without persisting. Returns a deterministic snapshot each call;
+     * idempotent with respect to `record()` ordering.
+     */
+    snapshot(now?: Date): ShadowParityReport;
+    /**
+     * Write the aggregated snapshot to JSON. Resolves to the path of the
+     * per-run file. Also writes/overwrites `latest.json` alongside.
+     *
+     * Creates `outputDir` if it doesn't exist.
+     */
+    persist(outputDir: string, now?: Date): Promise<string>;
+    /** Reset the accumulator. Preserves `enabled`. */
+    clear(): void;
+}
+/**
+ * Construct a harness. Reads `GITNEXUS_SHADOW_MODE` at construction time
+ * (not per-`record()` call) so repeated no-op records don't re-check the
+ * env var in the hot path.
+ */
+export declare function createShadowHarness(): ShadowHarness;

package/dist/core/ingestion/shadow-harness.js

@@ -0,0 +1,148 @@
+/**
+ * Shadow-mode parity harness — dual-run observability for the RFC #909
+ * registry rollout (RFC §6.3; Ring 2 PKG #923).
+ *
+ * ## What it does
+ *
+ *   - Exposes `record({ language, callsite, legacy, newResult })` for
+ *     every call site where the caller has BOTH a legacy-DAG resolution
+ *     and a new `Registry.lookup` resolution.
+ *   - Computes a `ShadowDiff` per record via shared `diffResolutions`
+ *     (#918) and accumulates them in a per-language bucket.
+ *   - At the end of a run, aggregates into a `ShadowParityReport` via
+ *     shared `aggregateDiffs` (#918) — per-language parity %,
+ *     evidence-kind breakdown of divergences, grand-total overall row.
+ *   - Optionally persists the report as JSON under
+ *     `.gitnexus/shadow-parity/` so the static dashboard at
+ *     `gitnexus/shadow-parity-dashboard/` can render it offline.
+ *
+ * ## What it does NOT do
+ *
+ *   - **Invoke either resolution path itself.** The caller must run
+ *     legacy + `Registry.lookup` and pass results in. The harness is a
+ *     side-car, not a dispatcher — this keeps call-processor integration
+ *     surgical when it lands (tracked as a follow-up; the shared model
+ *     doesn't dual-invoke on its own).
+ *   - **Flip anything.** `REGISTRY_PRIMARY_<LANG>` lives in
+ *     `registry-primary-flag.ts` (#924); the harness records the
+ *     caller-supplied "which side is primary" bit for each record so the
+ *     dashboard can label rows, but it does not consult the flag itself.
+ *
+ * ## Activation
+ *
+ * `GITNEXUS_SHADOW_MODE=1` (or `'true'`, `'yes'`, case-insensitive,
+ * trimmed) enables the harness. When disabled, `record()` is a cheap
+ * no-op: no accumulation, no allocation beyond the harness object
+ * itself. Callers can always construct a harness and hand it through;
+ * the "off" overhead is near-zero.
+ *
+ * ## Persistence shape
+ *
+ * When `persist()` is called, the harness writes TWO files:
+ *
+ *   - `<outputDir>/<runId>.json` — the timestamped snapshot (immutable)
+ *   - `<outputDir>/latest.json`  — a pointer that the dashboard reads
+ *
+ * Both files contain the same `PersistedShadowReport` payload:
+ *
+ *   {
+ *     schemaVersion: 1,
+ *     runId: "<iso-8601>-<rand>",
+ *     generatedAt: "<iso-8601>",
+ *     primaryByLanguage: { [lang]: "legacy" | "registry" },
+ *     report: <ShadowParityReport>
+ *   }
+ *
+ * Schema-version-gated so future format changes don't silently confuse
+ * older dashboards. The dashboard renders `report.perLanguage` rows and
+ * annotates each with `primaryByLanguage[lang]`.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { aggregateDiffs, diffResolutions, } from '../../_shared/index.js';
+/**
+ * Construct a harness. Reads `GITNEXUS_SHADOW_MODE` at construction time
+ * (not per-`record()` call) so repeated no-op records don't re-check the
+ * env var in the hot path.
+ */
+export function createShadowHarness() {
+    const enabled = parseShadowModeEnv(process.env['GITNEXUS_SHADOW_MODE']);
+    const records = [];
+    const primaryByLanguage = {};
+    const recordImpl = (input) => {
+        if (!enabled)
+            return;
+        const diff = diffResolutions(input.callsite, input.legacy, input.newResult);
+        records.push({ language: input.language, diff });
+        // Primary per-language is resolved by last-write. In practice a run
+        // is single-threaded with respect to flag readings, so this is
+        // deterministic; a language's primary cannot change mid-run.
+        primaryByLanguage[input.language] = input.primary;
+    };
+    const snapshotImpl = (now = new Date()) => {
+        return aggregateDiffs(records, now);
+    };
+    const persistImpl = async (outputDir, now = new Date()) => {
+        await fs.mkdir(outputDir, { recursive: true });
+        const report = snapshotImpl(now);
+        const runId = makeRunId(now);
+        const payload = {
+            schemaVersion: 1,
+            runId,
+            generatedAt: now.toISOString(),
+            primaryByLanguage,
+            report,
+        };
+        const json = JSON.stringify(payload, null, 2);
+        const perRunPath = path.join(outputDir, `${runId}.json`);
+        const latestPath = path.join(outputDir, 'latest.json');
+        await fs.writeFile(perRunPath, json, 'utf8');
+        await fs.writeFile(latestPath, json, 'utf8');
+        return perRunPath;
+    };
+    const clearImpl = () => {
+        records.length = 0;
+        for (const key of Object.keys(primaryByLanguage)) {
+            delete primaryByLanguage[key];
+        }
+    };
+    return {
+        enabled,
+        record: recordImpl,
+        size: () => records.length,
+        snapshot: snapshotImpl,
+        persist: persistImpl,
+        clear: clearImpl,
+    };
+}
+// ─── Internal helpers ─────────────────────────────────────────────────────
+/**
+ * Env-var parser for `GITNEXUS_SHADOW_MODE`. Accepts the same truthy
+ * conventions as `REGISTRY_PRIMARY_<LANG>` from #924: `'true'` / `'1'` /
+ * `'yes'`, case-insensitive, whitespace-trimmed. Anything else — including
+ * `undefined`, `''`, `'false'`, `'off'`, typos — is false.
+ */
+function parseShadowModeEnv(raw) {
+    if (raw === undefined)
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    return normalized === 'true' || normalized === '1' || normalized === 'yes';
+}
+/**
+ * Deterministic run id derived from the timestamp plus 4 random bytes
+ * of entropy. The timestamp comes first so files sort chronologically;
+ * the entropy suffix prevents collisions when multiple runs share a
+ * clock-second. Shape: `YYYYMMDD-HHMMSS-xxxxxxxx`.
+ */
+function makeRunId(now) {
+    const y = now.getUTCFullYear().toString().padStart(4, '0');
+    const m = (now.getUTCMonth() + 1).toString().padStart(2, '0');
+    const d = now.getUTCDate().toString().padStart(2, '0');
+    const h = now.getUTCHours().toString().padStart(2, '0');
+    const min = now.getUTCMinutes().toString().padStart(2, '0');
+    const s = now.getUTCSeconds().toString().padStart(2, '0');
+    const entropy = Math.floor(Math.random() * 0xffffffff)
+        .toString(16)
+        .padStart(8, '0');
+    return `${y}${m}${d}-${h}${min}${s}-${entropy}`;
+}

package/dist/core/ingestion/workers/parse-worker.d.ts

@@ -4,6 +4,7 @@ import { type MixedChainStep } from '../utils/call-analysis.js';
 import type { ConstructorBinding } from '../type-env.js';
 import type { NamedBinding } from '../named-bindings/types.js';
 import type { NodeLabel } from '../../../_shared/index.js';
+import type { ParsedFile } from '../../../_shared/index.js';
 interface ParsedNode {
     id: string;
     label: string;
@@ -174,6 +175,14 @@ export interface ParseWorkerResult {
     constructorBindings: FileConstructorBindings[];
     /** All-scope type bindings from TypeEnv for BindingAccumulator (includes function-local). */
     fileScopeBindings: FileScopeBindings[];
+    /**
+     * Per-file `ParsedFile` artifacts from the new scope-based resolution
+     * pipeline (RFC #909 Ring 2). Empty unless the file's provider implements
+     * `emitScopeCaptures` — default for every language today, so this is
+     * additive and leaves the legacy DAG untouched. Consumed by #921's
+     * finalize-orchestrator.
+     */
+    parsedFiles: ParsedFile[];
     skippedLanguages: Record<string, number>;
     fileCount: number;
 }

package/dist/core/ingestion/workers/parse-worker.js

@@ -43,6 +43,7 @@ import { generateId } from '../../../lib/utils.js';
 import { preprocessImportPath } from '../import-processor.js';
 import { extractVueScript, extractTemplateComponents, isVueSetupTopLevel, } from '../vue-sfc-extractor.js';
 import { buildMethodProps, arityForIdFromInfo, typeTagForId, constTagForId, buildCollisionGroups, } from '../utils/method-props.js';
+import { extractParsedFile } from '../scope-extractor-bridge.js';
 // ============================================================================
 // Worker-local parser + language map
 // ============================================================================
@@ -415,6 +416,7 @@ const processBatch = (files, onProgress) => {
         ormQueries: [],
         constructorBindings: [],
         fileScopeBindings: [],
+        parsedFiles: [],
         skippedLanguages: {},
         fileCount: 0,
     };
@@ -1017,11 +1019,25 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             console.warn(`Query execution failed for ${file.path}: ${err instanceof Error ? err.message : String(err)}`);
             continue;
         }
+        const provider = getProvider(language);
+        // RFC #909 Ring 2: produce a `ParsedFile` for the new scope-based
+        // resolution pipeline. No-op (returns undefined) for every language
+        // today — only fires once a provider implements `emitScopeCaptures`.
+        // Runs BEFORE legacy extraction and its result is independent: a
+        // failure here is caught inside `extractParsedFile` and does NOT
+        // affect the legacy DAG path that follows.
+        const parsedFile = extractParsedFile(provider, parseContent, file.path, (message) => {
+            if (parentPort)
+                parentPort.postMessage({ type: 'warning', message });
+            else
+                console.warn(message);
+        });
+        if (parsedFile !== undefined)
+            result.parsedFiles.push(parsedFile);
         // Pre-pass: extract heritage from query matches to build parentMap for buildTypeEnv.
         // Heritage edges (EXTENDS/IMPLEMENTS) are created by heritage-processor which runs
         // in PARALLEL with call-processor, so the graph edges don't exist when buildTypeEnv
         // runs. This pre-pass makes parent class information available for type resolution.
-        const provider = getProvider(language);
         const fileParentMap = new Map();
         if (provider.heritageExtractor) {
             for (const match of matches) {
@@ -1804,6 +1820,7 @@ let accumulated = {
     ormQueries: [],
     constructorBindings: [],
     fileScopeBindings: [],
+    parsedFiles: [],
     skippedLanguages: {},
     fileCount: 0,
 };
@@ -1830,6 +1847,7 @@ const mergeResult = (target, src) => {
     appendAll(target.ormQueries, src.ormQueries);
     appendAll(target.constructorBindings, src.constructorBindings);
     appendAll(target.fileScopeBindings, src.fileScopeBindings);
+    appendAll(target.parsedFiles, src.parsedFiles);
     for (const [lang, count] of Object.entries(src.skippedLanguages)) {
         target.skippedLanguages[lang] = (target.skippedLanguages[lang] || 0) + count;
     }
@@ -1878,6 +1896,7 @@ parentPort.on('message', (msg) => {
                 ormQueries: [],
                 constructorBindings: [],
                 fileScopeBindings: [],
+                parsedFiles: [],
                 skippedLanguages: {},
                 fileCount: 0,
             };

package/dist/core/run-analyze.d.ts

@@ -13,6 +13,12 @@ export interface AnalyzeCallbacks {
     onLog?: (message: string) => void;
 }
 export interface AnalyzeOptions {
+    /**
+     * Force a full re-index of the pipeline. Callers may OR this with
+     * other flags that imply re-analysis (e.g. `--skills`), so the value
+     * here is the PIPELINE-force signal, NOT the registry-collision
+     * bypass. See `allowDuplicateName` below.
+     */
     force?: boolean;
     embeddings?: boolean;
     skipGit?: boolean;
@@ -20,6 +26,21 @@ export interface AnalyzeOptions {
     skipAgentsMd?: boolean;
     /** Omit volatile symbol/relationship counts from AGENTS.md and CLAUDE.md. */
     noStats?: boolean;
+    /**
+     * User-provided alias for the registry `name` (#829). When set,
+     * forwarded to `registerRepo` so the indexed repo is stored under
+     * this alias instead of the path-derived basename.
+     */
+    registryName?: string;
+    /**
+     * Bypass the `RegistryNameCollisionError` guard and allow two paths
+     * to register under the same `name` (#829). Controlled by the
+     * dedicated `--allow-duplicate-name` CLI flag, intentionally
+     * independent from `--force` — users who hit the collision guard
+     * should be able to accept the duplicate without paying the cost
+     * of a pipeline re-index.
+     */
+    allowDuplicateName?: boolean;
 }
 export interface AnalyzeResult {
     repoName: string;

package/dist/core/run-analyze.js

@@ -13,7 +13,7 @@ import fs from 'fs/promises';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, createFTSIndex, loadCachedEmbeddings, } from './lbug/lbug-adapter.js';
 import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, } from '../storage/repo-manager.js';
-import { getCurrentCommit, hasGitDir } from '../storage/git.js';
+import { getCurrentCommit, hasGitDir, getInferredRepoName } from '../storage/git.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
 import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
 import { STALE_HASH_SENTINEL } from './lbug/schema.js';
@@ -65,7 +65,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
         if (currentCommit !== '') {
             return {
-                repoName: path.basename(repoPath),
+                repoName: options.registryName ?? getInferredRepoName(repoPath) ?? path.basename(repoPath),
                 repoPath,
                 stats: existingMeta.stats ?? {},
                 alreadyUpToDate: true,
@@ -218,12 +218,23 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             },
         };
         await saveMeta(storagePath, meta);
-        await registerRepo(repoPath, meta);
+        // Forward the --name alias and the registry-collision bypass bit.
+        // `allowDuplicateName` is its own concern — independent from the
+        // pipeline `force` above. The CLI maps it from
+        // `--allow-duplicate-name` only; `--force` and `--skills` both
+        // trigger pipeline re-run but never bypass the registry guard.
+        // The returned name is the one actually written to the registry
+        // (after applying the precedence chain in registerRepo) — reuse it
+        // so AGENTS.md / skill files reference the same name MCP clients
+        // will look up (#979).
+        const projectName = await registerRepo(repoPath, meta, {
+            name: options.registryName,
+            allowDuplicateName: options.allowDuplicateName,
+        });
         // Only attempt to update .gitignore when a .git directory is present.
         if (hasGitDir(repoPath)) {
             await addToGitignore(repoPath);
         }
-        const projectName = path.basename(repoPath);
         // ── Generate AI context files (best-effort) ───────────────────────
         let aggregatedClusterCount = 0;
         if (pipelineResult.communityResult?.communities) {

package/dist/core/search/phase-timer.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Per-phase wall-clock timing for the search pipeline and similar
+ * multi-stage flows. Designed to be called from query() with minimal
+ * ceremony and negligible overhead (< 0.1 ms per phase recorded).
+ *
+ * ### Sequential usage
+ *
+ * ```ts
+ * const t = new PhaseTimer();
+ * t.start('bm25'); await bm25Search(...); t.stop();
+ * t.start('merge'); doMerge(); t.stop();
+ * const phases = t.summary(); // { bm25: 42, merge: 3 }
+ * ```
+ *
+ * ### Concurrent usage (Promise.all)
+ *
+ * `start`/`stop` assume a single active phase at a time, which is wrong
+ * for concurrent work inside `Promise.all` — the second `start` would
+ * auto-stop the first and only one of the two would get timed. Use
+ * {@link PhaseTimer.time} to wrap each concurrent promise instead:
+ *
+ * ```ts
+ * const [a, b] = await Promise.all([
+ *   t.time('bm25', bm25Search(...)),
+ *   t.time('vector', semanticSearch(...)),
+ * ]);
+ * ```
+ *
+ * ### Pre-measured durations
+ *
+ * ```ts
+ * t.mark('inherited', 12.5);
+ * ```
+ */
+export declare class PhaseTimer {
+    private phases;
+    private current;
+    private t0;
+    /** Start a new phase. Implicitly stops the previous one, if any. */
+    start(phase: string): void;
+    /** Stop the current phase. No-op if no phase is active. */
+    stop(): void;
+    /**
+     * Record a pre-measured duration without touching the active phase.
+     * Use for concurrent operations inside `Promise.all` where
+     * `start`/`stop` would step on each other, or for durations imported
+     * from sub-systems. Additive across repeated calls with the same
+     * phase name. Ignores negative / non-finite inputs.
+     */
+    mark(phase: string, durationMs: number): void;
+    /**
+     * Wrap a promise with automatic timing. Records wall time via
+     * {@link PhaseTimer.mark} regardless of which other phases are
+     * active — safe to use inside `Promise.all`.
+     */
+    time<T>(phase: string, promise: Promise<T>): Promise<T>;
+    /**
+     * Snapshot of accumulated durations rounded to 0.1 ms. Stops the
+     * current phase if one is still running.
+     */
+    summary(): Record<string, number>;
+    /**
+     * Sum of every recorded phase duration.
+     *
+     * Note: for phases recorded via {@link PhaseTimer.time} or
+     * {@link PhaseTimer.mark} this is the *sum*, not the wall time —
+     * concurrent work overlaps and the sum can exceed the end-to-end
+     * wall time. Record wall time separately with `mark('wall', …)` if
+     * that distinction matters.
+     */
+    totalMs(): number;
+}

package/dist/core/search/phase-timer.js

@@ -0,0 +1,106 @@
+/**
+ * Per-phase wall-clock timing for the search pipeline and similar
+ * multi-stage flows. Designed to be called from query() with minimal
+ * ceremony and negligible overhead (< 0.1 ms per phase recorded).
+ *
+ * ### Sequential usage
+ *
+ * ```ts
+ * const t = new PhaseTimer();
+ * t.start('bm25'); await bm25Search(...); t.stop();
+ * t.start('merge'); doMerge(); t.stop();
+ * const phases = t.summary(); // { bm25: 42, merge: 3 }
+ * ```
+ *
+ * ### Concurrent usage (Promise.all)
+ *
+ * `start`/`stop` assume a single active phase at a time, which is wrong
+ * for concurrent work inside `Promise.all` — the second `start` would
+ * auto-stop the first and only one of the two would get timed. Use
+ * {@link PhaseTimer.time} to wrap each concurrent promise instead:
+ *
+ * ```ts
+ * const [a, b] = await Promise.all([
+ *   t.time('bm25', bm25Search(...)),
+ *   t.time('vector', semanticSearch(...)),
+ * ]);
+ * ```
+ *
+ * ### Pre-measured durations
+ *
+ * ```ts
+ * t.mark('inherited', 12.5);
+ * ```
+ */
+export class PhaseTimer {
+    phases = new Map();
+    current = null;
+    t0 = 0;
+    /** Start a new phase. Implicitly stops the previous one, if any. */
+    start(phase) {
+        this.stop();
+        this.current = phase;
+        this.t0 = performance.now();
+    }
+    /** Stop the current phase. No-op if no phase is active. */
+    stop() {
+        if (this.current !== null) {
+            const elapsed = performance.now() - this.t0;
+            this.phases.set(this.current, (this.phases.get(this.current) ?? 0) + elapsed);
+            this.current = null;
+        }
+    }
+    /**
+     * Record a pre-measured duration without touching the active phase.
+     * Use for concurrent operations inside `Promise.all` where
+     * `start`/`stop` would step on each other, or for durations imported
+     * from sub-systems. Additive across repeated calls with the same
+     * phase name. Ignores negative / non-finite inputs.
+     */
+    mark(phase, durationMs) {
+        if (!Number.isFinite(durationMs) || durationMs < 0)
+            return;
+        this.phases.set(phase, (this.phases.get(phase) ?? 0) + durationMs);
+    }
+    /**
+     * Wrap a promise with automatic timing. Records wall time via
+     * {@link PhaseTimer.mark} regardless of which other phases are
+     * active — safe to use inside `Promise.all`.
+     */
+    async time(phase, promise) {
+        const t0 = performance.now();
+        try {
+            return await promise;
+        }
+        finally {
+            this.mark(phase, performance.now() - t0);
+        }
+    }
+    /**
+     * Snapshot of accumulated durations rounded to 0.1 ms. Stops the
+     * current phase if one is still running.
+     */
+    summary() {
+        this.stop();
+        const out = {};
+        for (const [k, v] of this.phases)
+            out[k] = Math.round(v * 10) / 10;
+        return out;
+    }
+    /**
+     * Sum of every recorded phase duration.
+     *
+     * Note: for phases recorded via {@link PhaseTimer.time} or
+     * {@link PhaseTimer.mark} this is the *sum*, not the wall time —
+     * concurrent work overlaps and the sum can exceed the end-to-end
+     * wall time. Record wall time separately with `mark('wall', …)` if
+     * that distinction matters.
+     */
+    totalMs() {
+        this.stop();
+        let t = 0;
+        for (const v of this.phases.values())
+            t += v;
+        return Math.round(t * 10) / 10;
+    }
+}