gitnexus 1.6.13-rc.80 → 1.6.13-rc.82

package/dist/core/ingestion/languages/dart/package-config.d.ts

@@ -15,14 +15,21 @@ export interface DartPackageConfigOptions {
      * is listed and before its entries are opened.
      */
     readonly beforeEntryOpen?: (relativePath: string) => void | Promise<void>;
+    /**
+     * Test seam. Production calls omit it. Invoked after the directory is
+     * opened and before it is listed.
+     */
+    readonly beforeDirectoryList?: (relativePath: string) => void | Promise<void>;
 }
 /** Linux anchors child opens. macOS verifies them. Every other platform does neither. */
 export declare function pubspecWalkAnchored(): boolean;
 export declare function directoryOpenFlags(): number;
 /**
  * Path that lists the directory inode already open on `fd`.
- * Linux uses `/proc/self/fd/N` and macOS uses `/dev/fd/N`.
- * Other platforms have no such path; callers refuse instead of listing by name.
+ * Only Linux has one: `/proc/self/fd/N`. macOS refuses `opendir` on
+ * `/dev/fd/N` for a directory (ENOTDIR) and Node has no `fdopendir`, so the
+ * walker lists the lexical path and verifies the pinned chain around it.
+ * Every other platform returns null and is not walked.
  */
 export declare function descriptorDirectoryPath(fd: number): string | null;
 /**

package/dist/core/ingestion/languages/dart/package-config.js

@@ -94,14 +94,14 @@ function directoryIdentity(stat) {
 }
 /**
  * Path that lists the directory inode already open on `fd`.
- * Linux uses `/proc/self/fd/N` and macOS uses `/dev/fd/N`.
- * Other platforms have no such path; callers refuse instead of listing by name.
+ * Only Linux has one: `/proc/self/fd/N`. macOS refuses `opendir` on
+ * `/dev/fd/N` for a directory (ENOTDIR) and Node has no `fdopendir`, so the
+ * walker lists the lexical path and verifies the pinned chain around it.
+ * Every other platform returns null and is not walked.
  */
 export function descriptorDirectoryPath(fd) {
     if (process.platform === 'linux')
         return `/proc/self/fd/${fd}`;
-    if (process.platform === 'darwin')
-        return `/dev/fd/${fd}`;
     return null;
 }
 /**
@@ -204,11 +204,31 @@ async function openChildFile(frames, parentFd, name, lexicalPath) {
         return openLexicalFile(frames, lexicalPath);
     throw Object.assign(new Error('no descriptor anchor'), { code: 'ENOTSUP' });
 }
-async function listOpenedDirectory(handle, entryLimit) {
-    const listing = descriptorDirectoryPath(handle.fd);
-    if (listing === null) {
+/**
+ * List the directory open on the last frame of `frames`. Linux lists the
+ * pinned inode through its descriptor. macOS re-checks the pinned chain, lists
+ * the lexical path, then re-checks the chain, so a path replaced around the
+ * listing fails the walk instead of being listed.
+ */
+async function listOpenedDirectory(frames, entryLimit, beforeList) {
+    const frame = frames[frames.length - 1];
+    if (frame === undefined) {
+        throw Object.assign(new Error('no directory to list'), { code: 'EINVAL' });
+    }
+    const anchored = descriptorDirectoryPath(frame.handle.fd);
+    if (anchored === null && process.platform !== 'darwin') {
         throw Object.assign(new Error('no descriptor listing'), { code: 'ENOTSUP' });
     }
+    if (anchored === null)
+        await assertPinnedChain(frames);
+    if (beforeList)
+        await beforeList();
+    const entries = await readDirectoryBounded(anchored ?? frame.absolute, entryLimit);
+    if (anchored === null)
+        await assertPinnedChain(frames);
+    return entries;
+}
+async function readDirectoryBounded(listing, entryLimit) {
     const dir = await opendir(listing);
     const entries = [];
     try {
@@ -236,8 +256,16 @@ async function listOpenedDirectory(handle, entryLimit) {
  */
 export async function readDirectoryNoFollow(directory) {
     const opened = await openVerifiedDirectory(directory);
+    const frame = {
+        relative: '',
+        absolute: directory,
+        handle: opened.handle,
+        identity: opened.identity,
+        entries: [],
+        next: 0,
+    };
     try {
-        return await listOpenedDirectory(opened.handle, DART_PUBSPEC_DIRECTORY_ENTRY_LIMIT);
+        return await listOpenedDirectory([frame], DART_PUBSPEC_DIRECTORY_ENTRY_LIMIT);
     }
     finally {
         await opened.handle.close();
@@ -280,7 +308,8 @@ export async function loadDartPackageConfig(repoPath, options) {
         if (++visited > directoryLimit)
             return incomplete('directory-limit', frame.relative || '.');
         try {
-            frame.entries = await listOpenedDirectory(frame.handle, directoryEntryLimit);
+            const beforeList = options?.beforeDirectoryList;
+            frame.entries = await listOpenedDirectory(stack, directoryEntryLimit, beforeList ? () => beforeList(frame.relative) : undefined);
         }
         catch (error) {
             const reason = error.code === 'E2BIG' ? 'directory-entries' : 'read-directory';

package/dist/core/run-analyze.js

@@ -1035,18 +1035,33 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                     ? (table, indexName) => log(`FTS: ready ${table}.${indexName}`)
                     : undefined,
             });
-            const missing = await verifySearchFTSIndexes(executeQuery, ftsIndexes);
-            if (missing.length > 0) {
-                // #2889: name WHY each index is missing when the build itself said so.
-                // Repair now rebuilds every table it can before reporting, so the tables
-                // absent from this list were genuinely repaired even on a failed run —
-                // previously the first failure aborted the sweep and the message could
-                // only ever list "missing", never a reason. Same sentence the analyze
-                // degrade path prints, so one failure does not read two ways.
-                const reasons = repairFailures.length > 0
-                    ? ` ${summarizeFtsIndexBuildFailures(repairFailures, ftsIndexes)}.`
-                    : '';
-                throw new Error(`FTS repair failed - missing indexes after rebuild: ${missing.join(', ')}.${reasons} ` +
+            const catalogDiagnostics = [];
+            let missing = [];
+            let catalogError;
+            try {
+                missing = await verifySearchFTSIndexes(executeQuery, ftsIndexes, (diagnostic) => {
+                    catalogDiagnostics.push(diagnostic.message);
+                });
+            }
+            catch (error) {
+                // An unreadable catalog is unknown, not proof of missing indexes.
+                // Keep earlier native build errors when this read also fails.
+                catalogError = error instanceof Error ? error.message : String(error);
+            }
+            if (repairFailures.length > 0 || missing.length > 0 || catalogError !== undefined) {
+                // A failed DROP may leave a valid old catalog entry. Its presence must
+                // not certify that this repair succeeded or clear the recovery marker.
+                const reasons = [
+                    missing.length > 0 ? `missing indexes after rebuild: ${missing.join(', ')}` : '',
+                    repairFailures.length > 0
+                        ? summarizeFtsIndexBuildFailures(repairFailures, ftsIndexes)
+                        : missing.length > 0
+                            ? 'no build error was returned'
+                            : '',
+                    ...catalogDiagnostics,
+                    catalogError !== undefined ? `catalog verification failed: ${catalogError}` : '',
+                ].filter(Boolean);
+                throw new Error(`FTS repair failed - ${reasons.join('. ')}. ` +
                     'Run `gitnexus analyze --force` to perform a full graph+FTS rebuild; ' +
                     'if that also fails, verify FTS extension availability via `gitnexus doctor`.');
             }

package/dist/core/search/fts-indexes.d.ts

@@ -159,7 +159,18 @@ export declare function createSearchFTSIndexes(options?: CreateSearchFTSIndexesO
  * {@link redactPaths} first, the same rule the query-side warnings follow.
  */
 export declare const summarizeFtsIndexBuildFailures: (failures: readonly FtsIndexBuildFailure[], indexes?: readonly FTSIndexDefinition[]) => string;
-export declare function verifySearchFTSIndexes(executeQuery: (cypher: string) => Promise<unknown[]>, indexes?: readonly FTSIndexDefinition[]): Promise<string[]>;
+/** Bounded catalog evidence for CLI/log diagnostics, never source or index definitions. */
+export interface FtsIndexVerificationDiagnostic {
+    table: string;
+    indexName: string;
+    message: string;
+}
+/**
+ * Return missing or invalid configured indexes. An optional callback receives
+ * bounded evidence from the same catalog read; a failed read still throws and
+ * proves neither presence nor absence.
+ */
+export declare function verifySearchFTSIndexes(executeQuery: (cypher: string) => Promise<unknown[]>, indexes?: readonly FTSIndexDefinition[], onMismatch?: (diagnostic: FtsIndexVerificationDiagnostic) => void): Promise<string[]>;
 /**
  * Why an FTS build failed, so the caller can react correctly (#2658):
  *

package/dist/core/search/fts-indexes.js

@@ -1,4 +1,4 @@
-import { createFTSIndex, dropFTSIndex, indexRowName, indexRowTable, resolveGateRows, DEFAULT_FTS_STEMMER, } from '../lbug/lbug-adapter.js';
+import { createFTSIndex, dropFTSIndex, indexRowName, indexRowTable, indexRowType, resolveGateRows, DEFAULT_FTS_STEMMER, } from '../lbug/lbug-adapter.js';
 import { getFtsCapability } from '../lbug/extension-loader.js';
 import { FTS_DISABLED_MESSAGE } from './fts-policy.js';
 import { classifyExtensionLoadError, usesClassifiedLoadRemedy, } from '../lbug/extension-load-error.js';
@@ -312,38 +312,65 @@ export async function createSearchFTSIndexes(options) {
  */
 export const summarizeFtsIndexBuildFailures = (failures, indexes = FTS_INDEXES) => `FTS index build failed for ${failures.length} of ${indexes.length} tables: ` +
     failures.map((f) => `${f.table}.${f.indexName} (${f.error})`).join(', ');
-export async function verifySearchFTSIndexes(executeQuery, indexes = FTS_INDEXES) {
+const boundCatalogText = (text, limit) => text.length > limit ? `${text.slice(0, limit - 14)}… [truncated]` : text;
+const catalogFieldEvidence = (value) => typeof value === 'string'
+    ? JSON.stringify(boundCatalogText(value, 80))
+    : value === undefined
+        ? '<missing>'
+        : `<invalid ${value === null ? 'null' : typeof value}>`;
+const catalogPropertiesEvidence = (value) => {
+    if (!Array.isArray(value))
+        return `<invalid properties: ${catalogFieldEvidence(value)}>`;
+    return (`[${value.slice(0, 8).map(catalogFieldEvidence).join(', ')}]` +
+        (value.length > 8 ? ` (${value.length - 8} properties truncated)` : ''));
+};
+/**
+ * Return missing or invalid configured indexes. An optional callback receives
+ * bounded evidence from the same catalog read; a failed read still throws and
+ * proves neither presence nor absence.
+ */
+export async function verifySearchFTSIndexes(executeQuery, indexes = FTS_INDEXES, onMismatch) {
     // Read the catalog once and check each configured index both EXISTS and
     // covers its expected columns. A queryability-only probe (CALL QUERY_FTS_INDEX
     // ... catch) is not enough: a stale `name+content`-only index left on a
     // pre-#2299 DB stays queryable yet silently misses `description`, so the probe
     // would pass while doc-comment search is still broken (#2299). SHOW_INDEXES
     // exposes `property_names` (STRING[]) per index, so we assert coverage directly.
-    const rows = await executeQuery('CALL SHOW_INDEXES() RETURN *');
-    const propsByIndex = new Map();
-    for (const row of rows) {
-        if (typeof row !== 'object' || row === null)
-            continue;
-        const record = row;
-        const indexName = indexRowName(record);
-        // LADYBUGDB-CONTRACT: `property_names` is the one SHOW_INDEXES column with a
-        // single reader, so it has no shared accessor — see {@link IndexCatalogRow}
-        // in lbug-adapter.ts for the full column list and the re-validation rule.
-        // Unlike the gates, an unreadable shape here is safe: it reports the index as
-        // not covering its columns, i.e. "missing", which degrades keyword search
-        // loudly rather than passing a broken index off as verified.
-        const propertyNames = record.property_names;
-        if (typeof indexName !== 'string' || !Array.isArray(propertyNames))
-            continue;
-        propsByIndex.set(indexName, propertyNames.filter((p) => typeof p === 'string'));
-    }
+    const rows = (await executeQuery('CALL SHOW_INDEXES() RETURN *')).filter((row) => typeof row === 'object' && row !== null);
     const missing = [];
     for (const { table, indexName, properties } of indexes) {
-        const actual = propsByIndex.get(indexName);
-        // Absent from the catalog, or present but not covering every expected column.
-        if (!actual || !properties.every((p) => actual.includes(p))) {
-            missing.push(`${table}.${indexName}`);
-        }
+        const valid = rows.some((row) => {
+            // LADYBUGDB-CONTRACT: `property_names` is a named STRING[] column;
+            // identity/type use the shared catalog readers in lbug-adapter.ts.
+            const actual = row.property_names;
+            return (indexRowTable(row) === table &&
+                indexRowName(row) === indexName &&
+                indexRowType(row) === 'FTS' &&
+                Array.isArray(actual) &&
+                actual.every((property) => typeof property === 'string') &&
+                properties.every((property) => actual.includes(property)));
+        });
+        if (valid)
+            continue;
+        missing.push(`${table}.${indexName}`);
+        if (!onMismatch)
+            continue;
+        // Show only rows that could explain this identity mismatch, and only
+        // catalog identity/type/property fields. Malformed objects are represented
+        // by their type rather than serialized (they can carry arbitrary content).
+        const relevant = rows.filter((row) => indexRowTable(row) === table || indexRowName(row) === indexName);
+        const observed = relevant
+            .slice(0, 3)
+            .map((row) => `{table=${catalogFieldEvidence(indexRowTable(row))}, ` +
+            `index=${catalogFieldEvidence(indexRowName(row))}, ` +
+            `type=${catalogFieldEvidence(indexRowType(row))}, ` +
+            `properties=${catalogPropertiesEvidence(row.property_names)}}`);
+        const message = `${table}.${indexName}: expected table=${catalogFieldEvidence(table)}, ` +
+            `index=${catalogFieldEvidence(indexName)}, type=FTS, ` +
+            `properties=${catalogPropertiesEvidence(properties)}; observed ` +
+            (observed.length > 0 ? observed.join(', ') : 'no matching table or index name') +
+            (relevant.length > 3 ? ` (${relevant.length - 3} catalog rows truncated)` : '');
+        onMismatch({ table, indexName, message: boundCatalogText(message, 2048) });
     }
     return missing;
 }
@@ -418,28 +445,47 @@ export async function buildSearchIndexesOrDegrade(executeQuery, options) {
         // means description search is broken (#2299).
         const failures = await createSearchFTSIndexes(options);
         const indexes = options?.indexes ?? FTS_INDEXES;
-        const missing = await verifySearchFTSIndexes(executeQuery, indexes);
-        if (failures.length === 0 && missing.length === 0)
+        const diagnostics = [];
+        let missing = [];
+        let verificationError;
+        try {
+            missing = await verifySearchFTSIndexes(executeQuery, indexes, (diagnostic) => diagnostics.push(diagnostic));
+        }
+        catch (e) {
+            // A failed catalog read is unknown, not absence. Keep the native build
+            // failures already collected rather than replacing them with this error.
+            verificationError = e instanceof Error ? e.message : String(e);
+        }
+        if (failures.length === 0 && missing.length === 0 && verificationError === undefined) {
             return { ok: true };
-        // A table that failed to build is necessarily missing too — report it once,
-        // with its reason, and keep `missing` for indexes nothing explains.
+        }
+        // A failed DROP may leave an old catalog row present. Build failures stand
+        // on their own; avoid naming the same table again as an unexplained failure.
         const named = new Set(failures.map((f) => `${f.table}.${f.indexName}`));
-        const unexplained = missing.filter((name) => !named.has(name));
+        const unexplained = diagnostics.filter((d) => !named.has(`${d.table}.${d.indexName}`));
         const error = [
             failures.length > 0 ? summarizeFtsIndexBuildFailures(failures, indexes) : '',
             // Structural incompleteness with no thrown error — classified capability
             // (degrade) below, matching prior behavior; a broken *write* surfaces as
             // a thrown IO/checkpoint error and is classified integrity there.
-            unexplained.length > 0 ? `missing indexes after build: ${unexplained.join(', ')}` : '',
+            unexplained.length > 0
+                ? 'missing indexes or mismatched catalog rows after build ' +
+                    '(no build error was returned for these indexes): ' +
+                    unexplained.map((d) => d.message).join('; ')
+                : '',
+            verificationError !== undefined
+                ? `FTS catalog verification failed: ${verificationError}`
+                : '',
         ]
             .filter((part) => part.length > 0)
             .join('; ');
         // Classify per failure, not over the joined text: capability signatures are
         // checked first, so folding the messages together would let an untokenizable
         // row mask a genuinely broken write and downgrade an abort into a degrade.
-        const failureClass = failures.some((f) => classifyFtsBuildError(f.error) === 'integrity')
+        const failureClass = failures.some((f) => classifyFtsBuildError(f.error) === 'integrity') ||
+            (verificationError !== undefined && classifyFtsBuildError(verificationError) === 'integrity')
             ? 'integrity'
-            : classifyFtsBuildError(error);
+            : 'capability';
         return { ok: false, error, failureClass };
     }
     catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.13-rc.80",
+  "version": "1.6.13-rc.82",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -59,6 +59,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:cross-platform": "tsx scripts/run-cross-platform.ts",
+    "test:benchmarks": "node --import tsx scripts/run-benchmarks.ts",
     "postinstall": "node scripts/build-tree-sitter-grammars.cjs",
     "assert-publish-coverage": "node scripts/assert-publish-grammar-coverage.cjs",
     "prepare": "node scripts/build.js",

package/scripts/cross-platform-tests.ts

@@ -206,9 +206,8 @@ const LBUG_NATIVE = [
   // (the same reason fts-extension-e2e.test.ts is registered below), so the
   // FTS-unavailable branch has to run on a real Windows/macOS runner rather
   // than only on Ubuntu where FTS always loads. And its both-blocked case is
-  // gated on GITNEXUS_REQUIRE_VECTOR=1, which ci-tests.yml sets ONLY on this
-  // job — everywhere else an unavailable VECTOR extension skips instead of
-  // failing. Budget: four real analyze runs, so expect it to sit alongside the
+  // gated on GITNEXUS_REQUIRE_VECTOR=1, which ci-tests.yml requires in both
+  // coverage and platform jobs so an unavailable VECTOR fails loudly. Budget: four real analyze runs, so expect it to sit alongside the
   // VECTOR sibling's ~87s Windows measurement.
   'test/unit/incremental-index-extension-dml-gate.test.ts',
 ];
@@ -308,6 +307,10 @@ const NATIVE_ADDON_SMOKE = [
 // Filesystem behavior tests — exercise operations that vary across
 // platforms (CRLF, symlinks, permissions, temp dirs)
 const FILESYSTEM = [
+  // The deletion-guard cases in this file require real Windows path semantics.
+  'test/unit/canonicalize-path-long-path-prefix.test.ts',
+  'test/unit/storage-resolver.test.ts',
+  'test/unit/dart-package-imports.test.ts',
   // Cargo membership uses path normalization, descriptor validation, symlinks,
   // and Rust native parsing (including long Windows source strings).
   'test/unit/scope-resolution/rust-cargo-targets.test.ts',

package/scripts/execution-reporter.ts

@@ -0,0 +1,33 @@
+import { JsonReporter, type TestRunEndReason } from 'vitest/node';
+
+/** Vitest's stock JSON omits unhandled errors, even when success is true. */
+export default class ExecutionReporter extends JsonReporter {
+  private executionErrors = 0;
+  private executionReason: TestRunEndReason = 'interrupted';
+
+  constructor() {
+    super({});
+  }
+
+  override async onTestRunEnd(
+    modules: Parameters<JsonReporter['onTestRunEnd']>[0],
+    errors: readonly unknown[] = [],
+    reason: TestRunEndReason = 'interrupted',
+  ): Promise<void> {
+    this.executionErrors = errors.length;
+    this.executionReason = reason;
+    await super.onTestRunEnd(modules);
+  }
+
+  override async writeReport(json: string): Promise<void> {
+    const report = JSON.parse(json);
+    await super.writeReport(
+      JSON.stringify({
+        ...report,
+        success: report.success && this.executionErrors === 0 && this.executionReason === 'passed',
+        executionErrors: this.executionErrors,
+        executionReason: this.executionReason,
+      }),
+    );
+  }
+}

package/scripts/run-benchmarks.ts

@@ -0,0 +1,32 @@
+import { execFileSync } from 'node:child_process';
+import { globSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const root = fileURLToPath(new URL('../', import.meta.url));
+// Discover the opt-in suites from source so a new benchmark cannot silently
+// miss a hand-maintained workflow list. Keep wall-clock measurements serial.
+const files = globSync('test/**/*.test.ts', { cwd: root })
+  .filter((file) =>
+    /process\.env(?:\.GITNEXUS_BENCH|\[['"]GITNEXUS_BENCH['"]\])/.test(
+      readFileSync(new URL(`../${file.replaceAll('\\', '/')}`, import.meta.url), 'utf8'),
+    ),
+  )
+  .sort();
+if (!files.length) throw new Error('No benchmark test suites discovered');
+execFileSync(
+  process.execPath,
+  [
+    fileURLToPath(new URL('../node_modules/vitest/vitest.mjs', import.meta.url)),
+    'run',
+    '--no-file-parallelism',
+    ...files,
+    '--reporter=default',
+    '--reporter=./scripts/execution-reporter.ts',
+    '--outputFile=benchmarks.json',
+  ],
+  {
+    cwd: root,
+    stdio: 'inherit',
+    env: { ...process.env, GITNEXUS_BENCH: '1' },
+  },
+);

package/scripts/run-cross-platform.ts

@@ -80,8 +80,19 @@ console.log(
 );
 
 const startedAt = Date.now();
+const reportName = process.env.GITNEXUS_TEST_REPORT;
+if (reportName && !/^[a-zA-Z0-9_-]+\.json$/.test(reportName)) {
+  throw new Error('GITNEXUS_TEST_REPORT must be a JSON basename');
+}
+const reportArgs = reportName
+  ? [
+      '--reporter=default',
+      '--reporter=./scripts/execution-reporter.ts',
+      `--outputFile=${reportName}`,
+    ]
+  : [];
 try {
-  execFileSync('npx', ['vitest', 'run', ...files], {
+  execFileSync('npx', ['vitest', 'run', ...files, ...reportArgs], {
     cwd: ROOT,
     stdio: 'inherit',
     timeout: timeoutMs,

package/scripts/test-completeness.ts

@@ -0,0 +1,203 @@
+import { globSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import type { TestRunEndReason } from 'vitest/node';
+
+type Assertion = {
+  ancestorTitles: string[];
+  title: string;
+  fullName: string;
+  status: string;
+  location?: { line: number; column: number };
+};
+type Suite = {
+  name: string;
+  status: string;
+  assertionResults: Assertion[];
+  endTime?: number;
+  message?: string;
+};
+type Report = {
+  success?: boolean;
+  numTotalTests?: number;
+  startTime?: number;
+  executionErrors: number;
+  executionReason: TestRunEndReason;
+  testResults: Suite[];
+};
+
+/** Stable across GitHub's Linux, macOS and Windows checkout roots. */
+function testPath(name: string, packageName: string): string {
+  const normalized = name.replaceAll('\\', '/');
+  const relative =
+    normalized.match(new RegExp(`(?:^|/)${packageName}/((?:test|src)/.+)$`))?.[1] ?? normalized;
+  if (!/^(?:test|src)\/.+\.test\.[jt]sx?$/.test(relative)) {
+    throw new Error(`Invalid test report path: ${name}`);
+  }
+  return relative;
+}
+
+/** A skip is resolved only by a recorded pass of that same test in another job. */
+export function reconcileTestReports(
+  inputs: unknown[],
+  expectedFiles: string[] = [],
+  packageName = 'gitnexus',
+) {
+  if (inputs.length === 0) throw new Error('No execution reports supplied');
+  const tests = new Map<
+    string,
+    { file: string; assertion: Assertion; passed: boolean; failed: boolean }
+  >();
+  const failures = new Set<string>();
+  const failedSuites = new Set<string>();
+  const startTimes: number[] = [];
+  const endTimes: number[] = [];
+  for (const [index, input] of inputs.entries()) {
+    const report = input as Report;
+    if (!report || !Array.isArray(report.testResults) || report.testResults.length === 0) {
+      throw new Error(`Missing or empty execution report ${index}`);
+    }
+    if (report.success === false) failures.add(`Report ${index}: unsuccessful runner result`);
+    if (
+      !Number.isInteger(report.executionErrors) ||
+      report.executionErrors < 0 ||
+      !['passed', 'failed', 'interrupted'].includes(report.executionReason)
+    ) {
+      throw new Error(`Report ${index}: missing execution reporter evidence`);
+    }
+    if (report.executionErrors || report.executionReason !== 'passed') {
+      failures.add(
+        `Report ${index}: ${report.executionErrors} unhandled errors; ${report.executionReason}`,
+      );
+    }
+    if (typeof report.startTime === 'number') startTimes.push(report.startTime);
+    let count = 0;
+    const seen = new Set<string>();
+    for (const suite of report.testResults) {
+      const file = testPath(suite.name, packageName);
+      if (!Array.isArray(suite.assertionResults) || suite.assertionResults.length === 0) {
+        throw new Error(`No collected tests in ${file}`);
+      }
+      if (suite.status === 'failed') {
+        failures.add(`${file}: failed suite`);
+        failedSuites.add(file);
+      }
+      if (typeof suite.endTime === 'number') endTimes.push(suite.endTime);
+      for (const assertion of suite.assertionResults) {
+        if (
+          !['passed', 'failed', 'pending', 'skipped', 'todo', 'disabled'].includes(
+            assertion.status,
+          ) ||
+          !Array.isArray(assertion.ancestorTitles) ||
+          typeof assertion.title !== 'string' ||
+          (assertion.location !== undefined &&
+            (!Number.isInteger(assertion.location.line) ||
+              !Number.isInteger(assertion.location.column)))
+        ) {
+          throw new Error(`Malformed assertion in ${file}`);
+        }
+        // Collection order differs across platforms. Source location, not an
+        // ordinal, distinguishes equal titles declared at different locations.
+        // Helper-generated tests may have no location; their complete title
+        // must then be unique within the file (the duplicate check still applies).
+        const title = JSON.stringify([...assertion.ancestorTitles, assertion.title]);
+        const key = JSON.stringify([
+          file,
+          title,
+          assertion.location?.line ?? null,
+          assertion.location?.column ?? null,
+        ]);
+        if (seen.has(key))
+          throw new Error(
+            `Ambiguous test identity in ${file}: ${title}; give parameterized cases unique titles`,
+          );
+        seen.add(key);
+        const result = tests.get(key) ?? { file, assertion, passed: false, failed: false };
+        result.passed ||= assertion.status === 'passed';
+        result.failed ||= assertion.status === 'failed';
+        tests.set(key, result);
+        if (result.failed) failures.add(`${file}: ${assertion.fullName ?? title}`);
+        count++;
+      }
+    }
+    if (typeof report.numTotalTests === 'number' && report.numTotalTests !== count) {
+      throw new Error(`Report ${index}: expected ${report.numTotalTests} tests, found ${count}`);
+    }
+  }
+  const unverified = [...tests.values()]
+    .filter((test) => !test.passed && !test.failed)
+    .map((test) => `${test.file}: ${test.assertion.fullName}`);
+  const suites = new Map<string, Suite>();
+  for (const test of tests.values()) {
+    const status = test.failed ? 'failed' : test.passed ? 'passed' : 'pending';
+    const suite = suites.get(test.file) ?? {
+      name: test.file,
+      status: 'passed',
+      assertionResults: [],
+    };
+    suite.assertionResults.push({ ...test.assertion, status });
+    if (status === 'failed' || failedSuites.has(test.file)) suite.status = 'failed';
+    suites.set(test.file, suite);
+  }
+  for (const file of expectedFiles) {
+    if (!suites.has(file.replaceAll('\\', '/')))
+      throw new Error(`Test file was never collected: ${file}`);
+  }
+  const passed = [...tests.values()].filter((test) => test.passed && !test.failed).length;
+  const endTime = endTimes.length ? Math.max(...endTimes) : 0;
+  return {
+    total: tests.size,
+    passed,
+    unverified,
+    failures: [...failures],
+    report: {
+      success: failures.size === 0 && unverified.length === 0,
+      numTotalTests: tests.size,
+      numPassedTests: passed,
+      numFailedTests: [...tests.values()].filter((test) => test.failed).length,
+      numPendingTests: unverified.length,
+      numTotalTestSuites: suites.size,
+      numFailedTestSuites: failedSuites.size,
+      executionFailures: [...failures],
+      startTime: startTimes.length ? Math.min(...startTimes) : 0,
+      testResults: [...suites.values()].map((suite) => ({ ...suite, endTime })),
+    },
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  const [directory, output, shardsText] = process.argv.slice(2);
+  const shards = Number(shardsText);
+  if (!directory || !output || !Number.isInteger(shards) || shards < 1) {
+    throw new Error('Usage: test-completeness.ts <reports-dir> <output.json> <platform-shards>');
+  }
+  const names = ['coverage.json', 'benchmarks.json', 'preflight.json'];
+  for (const os of ['windows-latest', 'macos-latest']) {
+    for (let shard = 1; shard <= shards; shard++) names.push(`${os}-${shard}.json`);
+  }
+  // Exact expected receipts: an absent/cancelled job is never an empty success.
+  const root = fileURLToPath(new URL('../', import.meta.url));
+  const expected = globSync('test/**/*.test.ts', { cwd: root });
+  const result = reconcileTestReports(
+    names.map((name) => JSON.parse(readFileSync(path.join(directory, name), 'utf8'))),
+    expected,
+  );
+  writeFileSync(output, JSON.stringify(result.report));
+  console.log(
+    `Test execution: ${result.passed}/${result.total} passed; ${result.unverified.length} unverified; ${result.failures.length} failures`,
+  );
+  for (const message of [...result.unverified, ...result.failures]) console.error(message);
+  if (!result.report.success) process.exitCode = 1;
+  const webPath = path.join(root, '../gitnexus-web/web-test-results.json');
+  const web = reconcileTestReports(
+    [JSON.parse(readFileSync(webPath, 'utf8'))],
+    globSync('{test,src}/**/*.test.{ts,tsx}', { cwd: path.join(root, '../gitnexus-web') }),
+    'gitnexus-web',
+  );
+  writeFileSync(webPath, JSON.stringify(web.report));
+  console.log(
+    `Web execution: ${web.passed}/${web.total} passed; ${web.unverified.length} unverified; ${web.failures.length} failures`,
+  );
+  for (const message of [...web.unverified, ...web.failures]) console.error(message);
+  if (!web.report.success) process.exitCode = 1;
+}