@remnic/core 9.3.671 → 9.3.672

package/dist/lcm/engine.js

@@ -1,13 +1,13 @@
 import {
   LcmEngine,
   extractLcmConfig
-} from "../chunk-UOBLE67F.js";
+} from "../chunk-3IE22DJ2.js";
+import "../chunk-TPDBFYEG.js";
 import "../chunk-KCYE2MZM.js";
 import "../chunk-MAV46GWQ.js";
 import "../chunk-5VDJMYTF.js";
 import "../chunk-HP5FMB6L.js";
 import "../chunk-7N4KAIGN.js";
-import "../chunk-TPDBFYEG.js";
 import "../chunk-4RA3C3EV.js";
 import "../chunk-CI7RKSRE.js";
 import "../chunk-6KYMPV2O.js";

package/dist/lcm/index.js

@@ -5,7 +5,8 @@ import {
 import {
   LcmEngine,
   extractLcmConfig
-} from "../chunk-UOBLE67F.js";
+} from "../chunk-3IE22DJ2.js";
+import "../chunk-TPDBFYEG.js";
 import {
   assembleCompressedHistory
 } from "../chunk-KCYE2MZM.js";
@@ -23,7 +24,6 @@ import {
 import {
   LcmDag
 } from "../chunk-7N4KAIGN.js";
-import "../chunk-TPDBFYEG.js";
 import "../chunk-4RA3C3EV.js";
 import "../chunk-CI7RKSRE.js";
 import "../chunk-6KYMPV2O.js";

package/dist/namespaces/migrate.js

@@ -2,10 +2,10 @@ import {
   listNamespaces,
   runNamespaceMigration,
   verifyNamespaces
-} from "../chunk-LXVOZ2O6.js";
+} from "../chunk-ZUPFMHJA.js";
 import "../chunk-LZSMQHXC.js";
-import "../chunk-XS2CWEHZ.js";
-import "../chunk-23EBQ27U.js";
+import "../chunk-4QZ7H6FN.js";
+import "../chunk-EJYFPRED.js";
 import "../chunk-OUWAQVDJ.js";
 import "../chunk-DOCTITOP.js";
 import "../chunk-CYEPCZN5.js";
@@ -15,10 +15,10 @@ import "../chunk-AER6MT24.js";
 import "../chunk-RN7MUWON.js";
 import "../chunk-CINZGPSJ.js";
 import "../chunk-ZFXCQPNO.js";
-import "../chunk-CRO4LCQ6.js";
+import "../chunk-KJOYHNS7.js";
+import "../chunk-OIF36KGD.js";
 import "../chunk-7DTASS5T.js";
 import "../chunk-E6ZDCOHM.js";
-import "../chunk-OIF36KGD.js";
 import "../chunk-6RHNCKHG.js";
 import "../chunk-YNQ6DFSV.js";
 import "../chunk-O75CRYGF.js";

package/dist/namespaces/search.js

@@ -1,8 +1,8 @@
 import {
   NamespaceSearchRouter,
   namespaceCollectionName
-} from "../chunk-XS2CWEHZ.js";
-import "../chunk-23EBQ27U.js";
+} from "../chunk-4QZ7H6FN.js";
+import "../chunk-EJYFPRED.js";
 import "../chunk-OUWAQVDJ.js";
 import "../chunk-DOCTITOP.js";
 import "../chunk-CYEPCZN5.js";
@@ -12,10 +12,10 @@ import "../chunk-AER6MT24.js";
 import "../chunk-RN7MUWON.js";
 import "../chunk-CINZGPSJ.js";
 import "../chunk-ZFXCQPNO.js";
-import "../chunk-CRO4LCQ6.js";
+import "../chunk-KJOYHNS7.js";
+import "../chunk-OIF36KGD.js";
 import "../chunk-7DTASS5T.js";
 import "../chunk-E6ZDCOHM.js";
-import "../chunk-OIF36KGD.js";
 import "../chunk-6RHNCKHG.js";
 import "../chunk-YNQ6DFSV.js";
 import "../chunk-O75CRYGF.js";

package/dist/operator-toolkit.js

@@ -11,8 +11,8 @@ import {
   summarizeMemoryWorthLegacyCounters,
   summarizeObservationThroughput,
   summarizeTierDistribution
-} from "./chunk-CPVV2UEL.js";
-import "./chunk-LXVOZ2O6.js";
+} from "./chunk-FP4ISXI3.js";
+import "./chunk-ZUPFMHJA.js";
 import "./chunk-6T4LTI2F.js";
 import "./chunk-YBPYIAA5.js";
 import "./chunk-LZSMQHXC.js";
@@ -26,8 +26,8 @@ import "./chunk-PHK3HARR.js";
 import "./chunk-NDAH7BJ5.js";
 import "./chunk-Z5LAYHGJ.js";
 import "./chunk-VL5JJOOY.js";
-import "./chunk-XS2CWEHZ.js";
-import "./chunk-23EBQ27U.js";
+import "./chunk-4QZ7H6FN.js";
+import "./chunk-EJYFPRED.js";
 import "./chunk-OUWAQVDJ.js";
 import "./chunk-DOCTITOP.js";
 import "./chunk-CYEPCZN5.js";
@@ -37,10 +37,10 @@ import "./chunk-AER6MT24.js";
 import "./chunk-RN7MUWON.js";
 import "./chunk-CINZGPSJ.js";
 import "./chunk-ZFXCQPNO.js";
-import "./chunk-CRO4LCQ6.js";
+import "./chunk-KJOYHNS7.js";
+import "./chunk-OIF36KGD.js";
 import "./chunk-7DTASS5T.js";
 import "./chunk-E6ZDCOHM.js";
-import "./chunk-OIF36KGD.js";
 import "./chunk-6RHNCKHG.js";
 import "./chunk-YNQ6DFSV.js";
 import "./chunk-O75CRYGF.js";

package/dist/orchestrator.js

@@ -28,19 +28,19 @@ import {
   sanitizeSessionKeyForFilename,
   shouldFilterLifecycleRecallCandidate,
   summarizeGraphShadowComparison
-} from "./chunk-ZI6A7X4V.js";
+} from "./chunk-M3WF2AB6.js";
 import "./chunk-4SKKVWLQ.js";
 import "./chunk-7HYPN2GC.js";
 import "./chunk-666A3MOW.js";
 import "./chunk-HHLLAQGZ.js";
 import "./chunk-UWK5OXUJ.js";
-import "./chunk-UOBLE67F.js";
+import "./chunk-3IE22DJ2.js";
+import "./chunk-TPDBFYEG.js";
 import "./chunk-KCYE2MZM.js";
 import "./chunk-MAV46GWQ.js";
 import "./chunk-5VDJMYTF.js";
 import "./chunk-HP5FMB6L.js";
 import "./chunk-7N4KAIGN.js";
-import "./chunk-TPDBFYEG.js";
 import "./chunk-TECVW3JP.js";
 import "./chunk-T2PO5MUF.js";
 import "./chunk-B6IUW76R.js";
@@ -147,8 +147,8 @@ import "./chunk-RS25QOKZ.js";
 import "./chunk-JGSKJHF7.js";
 import "./chunk-FF4KLI5W.js";
 import "./chunk-6VP3YUCS.js";
-import "./chunk-XS2CWEHZ.js";
-import "./chunk-23EBQ27U.js";
+import "./chunk-4QZ7H6FN.js";
+import "./chunk-EJYFPRED.js";
 import "./chunk-OUWAQVDJ.js";
 import "./chunk-DOCTITOP.js";
 import "./chunk-CYEPCZN5.js";
@@ -158,10 +158,10 @@ import "./chunk-AER6MT24.js";
 import "./chunk-RN7MUWON.js";
 import "./chunk-CINZGPSJ.js";
 import "./chunk-ZFXCQPNO.js";
-import "./chunk-CRO4LCQ6.js";
+import "./chunk-KJOYHNS7.js";
+import "./chunk-OIF36KGD.js";
 import "./chunk-7DTASS5T.js";
 import "./chunk-E6ZDCOHM.js";
-import "./chunk-OIF36KGD.js";
 import "./chunk-6RHNCKHG.js";
 import "./chunk-YNQ6DFSV.js";
 import "./chunk-CI7RKSRE.js";

package/dist/search/factory.js

@@ -2,7 +2,7 @@ import {
   createConversationIndexRuntime,
   createConversationSearchBackend,
   createSearchBackend
-} from "../chunk-23EBQ27U.js";
+} from "../chunk-EJYFPRED.js";
 import "../chunk-OUWAQVDJ.js";
 import "../chunk-DOCTITOP.js";
 import "../chunk-CYEPCZN5.js";
@@ -11,10 +11,10 @@ import "../chunk-JOASJWQR.js";
 import "../chunk-AER6MT24.js";
 import "../chunk-RN7MUWON.js";
 import "../chunk-CINZGPSJ.js";
-import "../chunk-CRO4LCQ6.js";
+import "../chunk-KJOYHNS7.js";
+import "../chunk-OIF36KGD.js";
 import "../chunk-7DTASS5T.js";
 import "../chunk-E6ZDCOHM.js";
-import "../chunk-OIF36KGD.js";
 import "../chunk-6RHNCKHG.js";
 import "../chunk-YNQ6DFSV.js";
 import "../chunk-O75CRYGF.js";

package/dist/search/index.js

@@ -2,7 +2,7 @@ import {
   createConversationIndexRuntime,
   createConversationSearchBackend,
   createSearchBackend
-} from "../chunk-23EBQ27U.js";
+} from "../chunk-EJYFPRED.js";
 import {
   LanceDbBackend
 } from "../chunk-OUWAQVDJ.js";
@@ -25,10 +25,10 @@ import {
   EmbedHelper
 } from "../chunk-RN7MUWON.js";
 import "../chunk-CINZGPSJ.js";
-import "../chunk-CRO4LCQ6.js";
+import "../chunk-KJOYHNS7.js";
+import "../chunk-OIF36KGD.js";
 import "../chunk-7DTASS5T.js";
 import "../chunk-E6ZDCOHM.js";
-import "../chunk-OIF36KGD.js";
 import "../chunk-6RHNCKHG.js";
 import "../chunk-YNQ6DFSV.js";
 import "../chunk-O75CRYGF.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.3.671",
+  "version": "9.3.672",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -441,6 +441,16 @@
       "remnic-source": "./src/codex-thread-key.ts",
       "import": "./dist/codex-thread-key.js"
     },
+    "./coding/optional-coding-graph": {
+      "types": "./dist/coding/optional-coding-graph.d.ts",
+      "remnic-source": "./src/coding/optional-coding-graph.ts",
+      "import": "./dist/coding/optional-coding-graph.js"
+    },
+    "./coding/optional-coding-graph.js": {
+      "types": "./dist/coding/optional-coding-graph.d.ts",
+      "remnic-source": "./src/coding/optional-coding-graph.ts",
+      "import": "./dist/coding/optional-coding-graph.js"
+    },
     "./commitment-ledger": {
       "types": "./dist/commitment-ledger.d.ts",
       "remnic-source": "./src/commitment-ledger.ts",
@@ -2905,6 +2915,14 @@
     "agent",
     "core"
   ],
+  "peerDependencies": {
+    "@remnic/coding-graph": "^9.3.672"
+  },
+  "peerDependenciesMeta": {
+    "@remnic/coding-graph": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "node ./scripts/build-with-heap.mjs",
     "check-types": "tsc --noEmit",

package/src/coding/coding-graph-types.ts

@@ -0,0 +1,180 @@
+// Engine contract types for the optional @remnic/coding-graph package.
+//
+// These types are owned by @remnic/core so the base install compiles even
+// when @remnic/coding-graph is not present (it is an optional peer dep —
+// installed only on host machines that opt in to codebase-graph features).
+//
+// @remnic/coding-graph imports these types and implements them; it does
+// not redefine them. This breaks the type-source-direction cycle that
+// would otherwise require core to import coding-graph at compile time
+// (core's tsup DTS phase emits declarations against the package's
+// compiled output, which would fail when the optional package is not
+// installed in CI's base install).
+//
+// Dependency direction:
+//
+//     @remnic/core  ──── owns ───►  CodingGraphEngine (this file)
+//         ▲
+//         │ peer + devDep (workspace)
+//         │
+//     @remnic/coding-graph (implements against these types)
+//
+// Per #1551 PR1 — these are the full contract surface. PR2 fills the
+// extractors; PR3+ lands the walker, determinism, and grammarDir
+// behaviour behind the same `parseFile()` entry point.
+
+// ---------------------------------------------------------------------------
+// Version constant — surfaced through the engine instance so consumers can
+// advertise what they expect. Bumped in lockstep with the package version
+// during active development.
+// ---------------------------------------------------------------------------
+export const CODING_GRAPH_ENGINE_VERSION = "0.1.0-pr1" as const;
+
+// ---------------------------------------------------------------------------
+// Tier-1 language list — declared here so consumers can drive their own
+// tools against the engine without touching the optional package. Order is
+// stable; per-language configuration is the engine's concern.
+// ---------------------------------------------------------------------------
+export const TIER_1_LANGUAGES = [
+  "typescript",
+  "tsx",
+  "javascript",
+  "python",
+  "go",
+  "rust",
+  "java",
+  "c",
+  "cpp",
+  "csharp",
+  "ruby",
+  "php",
+  "kotlin",
+  "swift",
+  "bash",
+] as const;
+
+export type CodingGraphLanguage = (typeof TIER_1_LANGUAGES)[number];
+
+// ---------------------------------------------------------------------------
+// Tagged error code — the load-bearing signal for programmatic detection of
+// placeholder / install / load failure states. New codes must be added here
+// so consumers see them via TypeScript.
+// ---------------------------------------------------------------------------
+export type CodingGraphErrorCode =
+  | "not_implemented"
+  | "module_load_failed";
+
+// ---------------------------------------------------------------------------
+// Engine interface — the contract coding-graph implements against.
+// ---------------------------------------------------------------------------
+export interface CodingGraphEngine {
+  /** Engine version reported at construction time. */
+  readonly engineVersion: string;
+  /** Tier-1 languages this build supports (PR2 narrows by grammar availability). */
+  readonly supportedLanguages: readonly CodingGraphLanguage[];
+  /**
+   * Parse a single source file and emit its FileIR.
+   *
+   * PR1 throws `CodingGraphError("not_implemented", …)`. PR2 will return
+   * `ParseResult`; failure paths come back as
+   * `{ ok: false, code: "parse_failed", path, message }` (rule 44) rather
+   * than partial / silent IR.
+   */
+  parseFile(input: ParseFileInput): Promise<ParseResult>;
+  /** Engine lifecycle — release any cached parsers/grammars. */
+  dispose(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Parse input/output
+// ---------------------------------------------------------------------------
+export interface ParseFileInput {
+  /** Repository-relative path (forward slashes; no leading `./`). */
+  readonly path: string;
+  /** Raw file bytes; hashing happens inside the engine (rule 23). */
+  readonly content: Uint8Array;
+  /**
+   * Optional override. When omitted the engine sniffs the language from
+   * `path` extensions against its built-in tier-1 list (PR2).
+   */
+  readonly language?: CodingGraphLanguage;
+}
+
+export type ParseResult =
+  | { readonly ok: true; readonly ir: FileIR }
+  | {
+      readonly ok: false;
+      readonly code: "parse_failed";
+      readonly path: string;
+      readonly message: string;
+    };
+
+// ---------------------------------------------------------------------------
+// FileIR — the seam between the parser (optional package) and the graph
+// store (sibling issue #1552). Field types are the minimal viable set per
+// the issue's design section.
+// ---------------------------------------------------------------------------
+export interface FileIR {
+  readonly path: string;
+  readonly language: CodingGraphLanguage;
+  /** SHA-256 of the raw bytes; rule 23 — every consumer hashes the same form. */
+  readonly contentHash: string;
+  readonly symbols: readonly SymbolIR[];
+  readonly imports: readonly ImportIR[];
+  readonly exports: readonly ExportIR[];
+  readonly callSites: readonly CallSiteIR[];
+  readonly routes: readonly RouteIR[];
+}
+
+export interface SymbolIR {
+  readonly kind:
+    | "function"
+    | "class"
+    | "method"
+    | "interface"
+    | "enum"
+    | "type"
+    | "module";
+  readonly name: string;
+  readonly qualifiedName: string;
+  /** Half-open byte span `[startByte, endByte)`. Rule 35. */
+  readonly span: { readonly startByte: number; readonly endByte: number };
+  readonly parentQualifiedName?: string;
+}
+
+export interface ImportIR {
+  /** Raw module specifier as written in source. */
+  readonly module: string;
+  readonly importedNames: readonly string[];
+  readonly span: { readonly startByte: number; readonly endByte: number };
+}
+
+export interface ExportIR {
+  readonly name: string;
+  readonly span: { readonly startByte: number; readonly endByte: number };
+}
+
+export interface CallSiteIR {
+  readonly calleeNameCandidates: readonly string[];
+  readonly span: { readonly startByte: number; readonly endByte: number };
+}
+
+export interface RouteIR {
+  /** HTTP verb in upper-case, or framework-native verb (e.g. "ANY"). */
+  readonly verb: string;
+  readonly pathTemplate: string;
+  readonly handlerQualifiedName: string;
+  readonly span: { readonly startByte: number; readonly endByte: number };
+}
+
+// ---------------------------------------------------------------------------
+// Factory options
+// ---------------------------------------------------------------------------
+/**
+ * Reserved for PR2. Declared now so the public surface is stable; the
+ * options object is intentionally empty in PR1.
+ */
+export interface CreateCodingGraphEngineOptions {
+  /** Reserved for PR2: extra grammar directory supplied by the operator. */
+  readonly grammarDir?: never;
+}

package/src/coding/optional-coding-graph-cache.test.ts

@@ -0,0 +1,86 @@
+// Regression tests for Cursor Bugbot P2 round 3 on PR #1588:
+// "Probe poisons loader error path" and the round-5 "Loader skips
+// success cache" follow-up.
+//
+// These tests must work both when @remnic/coding-graph is installed
+// (workspace dev scenario) AND when it is absent (CI base install —
+// the optional peer is not symlinked). Conditional branches keep the
+// tests durable across install scenarios (P2 P2 P2 chatgpt-codex on
+// PR #1588 round 6).
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  isCodingGraphInstalled,
+  loadCodingGraphEngineFactory,
+  tryLoadCodingGraphModule,
+} from "./optional-coding-graph.js";
+
+test("loadCodingGraphEngineFactory fresh-attempts regardless of probe state", async () => {
+  // Probe and load side-by-side. Both must agree on the package's
+  // presence at this instant. When @remnic/coding-graph is absent
+  // (CI base install) the probe returns null and the loader throws
+  // the install hint. When present (dev workspace) both succeed.
+  const probeResult = await tryLoadCodingGraphModule();
+  const installed = await isCodingGraphInstalled();
+
+  if (probeResult === null) {
+    assert.equal(installed, false);
+    let threw = false;
+    let message = "";
+    try {
+      await loadCodingGraphEngineFactory();
+    } catch (err) {
+      threw = true;
+      message = err instanceof Error ? err.message : String(err);
+    }
+    assert.equal(threw, true, "loader must throw install hint when probe returned null");
+    assert.match(message, /@remnic\/coding-graph/);
+    assert.match(message, /npm install @remnic\/coding-graph/);
+    return;
+  }
+
+  // Package present.
+  assert.equal(installed, true);
+  const factory = await loadCodingGraphEngineFactory();
+  assert.equal(typeof factory, "function");
+});
+
+test("probe short-circuits to the same answer on repeated calls", async () => {
+  // Probe must be deterministic — repeated calls return the same
+  // answer. Both branches are valid (present → module, absent → null).
+  const a = await tryLoadCodingGraphModule();
+  const b = await tryLoadCodingGraphModule();
+  const aKind = a === null ? "null" : "module";
+  const bKind = b === null ? "null" : "module";
+  assert.equal(aKind, bKind, "consecutive probe calls must agree");
+});
+
+test("loader path is independent of the probe result", async () => {
+  // The Bugbot P2 round 3 bug was: a probe that caught a non-specifier
+  // import error was caching `null` into the load-path. That poisoned
+  // the user-facing loader path. This test asserts the load-path
+  // ALWAYS attempts a fresh import — proven by exercising the path
+  // for both present and absent packages.
+  const probe = await tryLoadCodingGraphModule();
+  if (probe === null) {
+    // Absent: loader throws install hint.
+    let threw = false;
+    try {
+      await loadCodingGraphEngineFactory();
+    } catch {
+      threw = true;
+    }
+    assert.equal(threw, true, "loader throws when package is absent");
+  } else {
+    // Present: loader returns a callable factory.
+    const factory = await loadCodingGraphEngineFactory();
+    assert.equal(typeof factory, "function");
+    assert.throws(() => factory(), (err: unknown) => {
+      if (!err || typeof err !== "object") return false;
+      const e = err as { name?: unknown; code?: unknown };
+      return e.name === "CodingGraphError" && e.code === "not_implemented";
+    });
+  }
+});

package/src/coding/optional-coding-graph-cacheread.test.ts

@@ -0,0 +1,78 @@
+// Regression tests for Cursor Bugbot P3 round 5 on PR #1588:
+// "Loader skips success cache".
+//
+// These tests must work both when @remnic/coding-graph is installed
+// (workspace dev scenario) AND when it is absent (CI base install —
+// the optional peer is not symlinked). chatgpt-codex round 6 P2:
+// the original test assumed the package is installed and would fail
+// in a core-only install. Every assertion below is conditional.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  isCodingGraphInstalled,
+  loadCodingGraphEngineFactory,
+  tryLoadCodingGraphModule,
+} from "./optional-coding-graph.js";
+
+test("loadCodingGraphEngineFactory returns a callable factory (install present)", async () => {
+  const installed = await isCodingGraphInstalled();
+  if (!installed) {
+    // Skip when package is absent (CI base install).
+    return;
+  }
+  const factory = await loadCodingGraphEngineFactory();
+  assert.equal(typeof factory, "function");
+});
+
+test("loadCodingGraphEngineFactory throws install hint when package absent", async () => {
+  const installed = await isCodingGraphInstalled();
+  if (installed) {
+    return;
+  }
+  let threw = false;
+  let message = "";
+  try {
+    await loadCodingGraphEngineFactory();
+  } catch (err) {
+    threw = true;
+    message = err instanceof Error ? err.message : String(err);
+  }
+  assert.equal(threw, true);
+  assert.match(message, /@remnic\/coding-graph/);
+  assert.match(message, /npm install @remnic\/coding-graph/);
+});
+
+test("after a successful load, tryLoadCodingGraphModule returns the same module (cache fast-path)", async () => {
+  const installed = await isCodingGraphInstalled();
+  if (!installed) return;
+  // Seed the success cache by calling loadCodingGraphEngineFactory.
+  const factory = await loadCodingGraphEngineFactory();
+  assert.equal(typeof factory, "function");
+  // A fresh probe call should return the cached module reference.
+  const probeResult = await tryLoadCodingGraphModule();
+  assert.ok(probeResult !== null);
+  // Invoking the factory throws the placeholder (PR1 contract).
+  assert.throws(() => factory(), (err: unknown) => {
+    if (!err || typeof err !== "object") return false;
+    const e = err as { name?: unknown; code?: unknown };
+    return e.name === "CodingGraphError" && e.code === "not_implemented";
+  });
+});
+
+test("loader fresh-attempts after the package is detected as missing", async () => {
+  // If present, loader returns a factory.
+  // If absent, loader throws the install hint.
+  try {
+    const factory = await loadCodingGraphEngineFactory();
+    assert.equal(typeof factory, "function");
+  } catch (err) {
+    if (err instanceof Error) {
+      assert.match(err.message, /@remnic\/coding-graph/);
+      assert.match(err.message, /npm install @remnic\/coding-graph/);
+      return;
+    }
+    throw err;
+  }
+});

package/src/coding/optional-coding-graph-concurrent.test.ts

@@ -0,0 +1,48 @@
+// Regression tests for Cursor Bugbot P2 round 4 on PR #1588:
+// "Concurrent probe calls return null".
+//
+// These tests assert concurrent probes observe the same kind of
+// outcome (module-or-null), independent of whether the package is
+// installed. chatgpt-codex round 6 P2: previous tests assumed the
+// package was installed and would fail in a core-only install.
+// Every assertion below is conditional on the current install state.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  isCodingGraphInstalled,
+  tryLoadCodingGraphModule,
+} from "./optional-coding-graph.js";
+
+test("two probes fired in the same tick must observe the same outcome kind", async () => {
+  // Kick off two probes back-to-back. They both observe the same
+  // outcome (module-or-null), regardless of presence.
+  const a = await tryLoadCodingGraphModule();
+  const b = await tryLoadCodingGraphModule();
+  const aKind = a === null ? "null" : "module";
+  const bKind = b === null ? "null" : "module";
+  assert.equal(aKind, bKind, "concurrent probes must produce the same kind of outcome");
+});
+
+test("many parallel probes never observe a transient null", async () => {
+  // 8 parallel probes; every one must observe the same outcome kind.
+  const probes = Array.from({ length: 8 }, () => tryLoadCodingGraphModule());
+  const results = await Promise.all(probes);
+  const nullCount = results.filter((r) => r === null).length;
+  const moduleCount = results.filter((r) => r !== null).length;
+  // All-or-nothing: every probe must agree.
+  assert.ok(
+    nullCount === 0 || moduleCount === 0,
+    "no probe in a parallel batch may report a different outcome than the others",
+  );
+  assert.equal(nullCount + moduleCount, 8);
+});
+
+test("isCodingGraphInstalled stays truthful under parallel calls", async () => {
+  const flags = await Promise.all(Array.from({ length: 8 }, () => isCodingGraphInstalled()));
+  // All parallel invocations must agree on the boolean.
+  const allTrue = flags.every((f) => f === true);
+  const allFalse = flags.every((f) => f === false);
+  assert.ok(allTrue || allFalse, "parallel probes must all agree on the boolean");
+});