@mrciphersmith/keryx 0.2.48 → 0.2.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.48",
+  "version": "0.2.50",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdgraph/enrich.ts

@@ -12,13 +12,17 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import {
-  resolveCapability,
   runCapabilityOrFallback,
   type CapabilityAdapter,
   type CapabilitySpec,
 } from "../capability/seam";
 import { loadGdgraphConfig } from "./config";
-import { createTreesitterSpec, type BuildInput, type FileRecord } from "./treesitter/adapter";
+import {
+  createTreesitterSpec,
+  resolveTreesitterCapability,
+  type BuildInput,
+  type FileRecord,
+} from "./treesitter/adapter";
 import type { SymbolLayer } from "./types";
 
 export interface EnrichResult {
@@ -37,18 +41,31 @@ export type CapabilityResolver = (
 export async function enrichBuildWithSymbols(
   cwd: string,
   files: FileRecord[],
-  resolve: CapabilityResolver = resolveCapability,
+  // `undefined` (the default) selects the T6 literal-import fast path via
+  // `resolveTreesitterCapability`; tests pass an explicit `CapabilityResolver`
+  // (e.g. a mock adapter, or the raw seam) to bypass it.
+  resolve?: CapabilityResolver,
 ): Promise<EnrichResult> {
   const config = await loadGdgraphConfig(cwd);
-  const spec = createTreesitterSpec(cwd, {
+  const treesitterConfig = {
     languages: config.treesitter.languages,
     grammarsPath: config.treesitter.grammarsPath,
-  });
+  };
 
   // Gate 1 (manifest-enabled) + dep + grammar + isAvailable. `null` ⇒ degrade
   // with NO symbol files written; the seam emits the single warn-once on an
-  // enabled-but-unavailable ceiling.
-  const adapter = await resolve(cwd, spec);
+  // enabled-but-unavailable ceiling. The default resolver additionally tries a
+  // literal `await import("web-tree-sitter")` fast path first (T6) so a
+  // `bun build --compile` binary can genuinely parse instead of always
+  // degrading — see `resolveTreesitterCapability`.
+  //
+  // `createTreesitterSpec` is only built here when an injected `resolve` is
+  // supplied (tests): `resolveTreesitterCapability` builds its own equivalent
+  // spec internally from `treesitterConfig`, so building one unconditionally
+  // on the default path would be dead work on every real `gdgraph build` call.
+  const adapter = resolve
+    ? await resolve(cwd, createTreesitterSpec(cwd, treesitterConfig))
+    : await resolveTreesitterCapability(cwd, treesitterConfig);
   if (!adapter) {
     return { enriched: false, symbols: 0, calls: 0 };
   }

package/src/gdgraph/treesitter/adapter.test.ts

@@ -2,12 +2,40 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { expect, test } from "bun:test";
-import { createTreesitterSpec, type BuildInput } from "./adapter";
+import { beforeEach, expect, mock, test } from "bun:test";
+import { createTreesitterSpec, resolveTreesitterCapability, type BuildInput } from "./adapter";
 import type { TsNode } from "./extract";
 import { enrichBuildWithSymbols } from "../enrich";
+import { hasWarned, resetWarnOnce } from "../../capability/warn-once";
+import { setTreesitterEnabled } from "../symbols-capability";
 import type { CallEdge, SymbolLayer, SymbolNode } from "../types";
 
+// Registered at MODULE TOP LEVEL, before any `test()` body runs: Bun loads
+// every test file's static imports/module body in a resolution pass before
+// running any test's body, so a `mock.module` call placed here reliably wins
+// the specifier UNTIL some test anywhere in the same `bun test` invocation
+// performs a real `await import("web-tree-sitter")` first (e.g.
+// `fallback.test.ts`'s AC4.3 test does exactly that with the capability
+// enabled) — once that happens, Bun's module cache is warmed with the real
+// module and this mock's factory is no longer invoked for later imports in
+// the same process. That makes `webTreeSitterImportAttempts` a reliable
+// "definitely zero attempts" signal (nothing increments it unless OUR mock's
+// factory ran) but NOT a reliable "definitely attempted" signal when run
+// alongside the rest of the suite — the enabled-path test below therefore
+// proves "gate 1 passed and we reached the real isAvailable() probe" via the
+// process-scoped warn-once tracker instead, which is correct regardless of
+// which physical module served the import.
+let webTreeSitterImportAttempts = 0;
+mock.module("web-tree-sitter", () => {
+  webTreeSitterImportAttempts += 1;
+  function MockParser(this: unknown): void {}
+  (MockParser as unknown as { init: () => Promise<void> }).init = async () => {};
+  (MockParser as unknown as { Language: { load: (p: string) => Promise<unknown> } }).Language = {
+    load: async () => ({}),
+  };
+  return { default: MockParser };
+});
+
 // --- tiny structural mock tree: one top-level function `boot` that calls `tick` ---
 function mk(o: {
   type: string;
@@ -247,3 +275,118 @@ test("Python grammar resolution — grammarForFile selects python for .py files"
     await rm(root, { recursive: true, force: true });
   }
 });
+
+// --- Real default (no-injected-resolver) production path (T6 review fix) ---
+//
+// Every test above injects an explicit `CapabilityResolver`/`dep`, bypassing
+// `resolveTreesitterCapability` entirely. The REAL call site
+// (`build.ts` → `enrichBuildWithSymbols(projectRoot, fileRecords)`, no
+// resolver argument) goes through `resolveTreesitterCapability`'s literal
+// `await import("web-tree-sitter")` fast path with NO injected resolver at
+// all. These tests exercise that exact default path and, via the
+// module-top-level `mock.module` above, directly observe whether the literal
+// import was attempted — proving gate 1 (manifest-enabled) runs BEFORE the
+// import, not after (the bug this ordering fixes).
+
+beforeEach(() => {
+  webTreeSitterImportAttempts = 0;
+});
+
+async function makeDisabledOrAbsentWorkspace(enabled: "absent" | false): Promise<string> {
+  const root = await mkdtemp(path.join(tmpdir(), "keryx-ts-default-"));
+  if (enabled === false) {
+    await mkdir(path.join(root, ".metaproject"), { recursive: true });
+    const manifest = setTreesitterEnabled({}, false);
+    await writeFile(
+      path.join(root, ".metaproject", "metaproject.json"),
+      JSON.stringify(manifest),
+      "utf8",
+    );
+  }
+  // enabled === "absent" ⇒ no .metaproject/metaproject.json at all (missing
+  // manifest = off, per seam.ts's own contract).
+  return root;
+}
+
+test("default path, capability DISABLED (missing manifest) — resolveTreesitterCapability never attempts the web-tree-sitter import", async () => {
+  const root = await makeDisabledOrAbsentWorkspace("absent");
+  try {
+    const adapter = await resolveTreesitterCapability(root, {
+      languages: ["typescript"],
+      grammarsPath: null,
+    });
+    expect(adapter).toBeNull();
+    // The core assertion (Fix 1): a disabled/missing-manifest ceiling must
+    // resolve to null WITHOUT ever attempting the literal dep import.
+    expect(webTreeSitterImportAttempts).toBe(0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("default path, capability DISABLED (enabled: false) — resolveTreesitterCapability never attempts the web-tree-sitter import", async () => {
+  const root = await makeDisabledOrAbsentWorkspace(false);
+  try {
+    const adapter = await resolveTreesitterCapability(root, {
+      languages: ["typescript"],
+      grammarsPath: null,
+    });
+    expect(adapter).toBeNull();
+    expect(webTreeSitterImportAttempts).toBe(0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("default path, capability DISABLED — enrichBuildWithSymbols (no injected resolver) degrades cleanly with no writes and no dep-load attempt", async () => {
+  const root = await makeDisabledOrAbsentWorkspace("absent");
+  try {
+    // No third argument ⇒ the real production default path (build.ts calls
+    // enrichBuildWithSymbols with exactly two arguments).
+    const result = await enrichBuildWithSymbols(root, [{ path: "src/x.ts", content: "" }]);
+    expect(result).toEqual({ enriched: false, symbols: 0, calls: 0 });
+    expect(webTreeSitterImportAttempts).toBe(0);
+
+    const storage = path.join(root, ".metaproject", "data", "gdgraph", "storage");
+    await expect(readFile(path.join(storage, "symbols.jsonl"), "utf8")).rejects.toThrow();
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("default path, capability ENABLED — resolveTreesitterCapability gets past gate 1 and reaches the real isAvailable() probe", async () => {
+  resetWarnOnce();
+  const root = await mkdtemp(path.join(tmpdir(), "keryx-ts-default-enabled-"));
+  try {
+    await mkdir(path.join(root, ".metaproject"), { recursive: true });
+    const manifest = setTreesitterEnabled({}, true);
+    await writeFile(
+      path.join(root, ".metaproject", "metaproject.json"),
+      JSON.stringify(manifest),
+      "utf8",
+    );
+
+    // No grammarsPath and no lockfile entries ⇒ resolveGrammars deterministically
+    // resolves zero grammars ⇒ isAvailable() is false, so this proves the
+    // manifest gate short-circuits correctly on the enabled side too, without
+    // requiring a real compiled binary or a real WASM grammar asset.
+    const adapter = await resolveTreesitterCapability(root, {
+      languages: ["typescript"],
+      grammarsPath: null,
+    });
+
+    // No grammar resolves ⇒ isAvailable() is false ⇒ degrades to null, same
+    // AC0-8 catch-and-degrade contract as the seam.
+    expect(adapter).toBeNull();
+    // Gate 1 passed (unlike the disabled cases above) and execution reached
+    // the real `isAvailable()` probe, which reported unavailable and warned
+    // once — the process-scoped warn-once tracker is a reliable,
+    // ordering-independent witness of this (unlike counting the mock
+    // factory's own invocations, which only fires when THIS file's mock wins
+    // the module-cache race against any real `web-tree-sitter` import
+    // elsewhere in a full-suite run — see the top-of-file comment).
+    expect(hasWarned("gdgraph.treesitter")).toBe(true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/gdgraph/treesitter/adapter.ts

@@ -10,7 +10,8 @@
 // It NEVER throws out (C0-11): every parse error is caught and the file is
 // skipped, so an opt-in ceiling can never break the deterministic seam.
 
-import type { CapabilityAdapter, CapabilitySpec } from "../../capability/seam";
+import { isCapabilityEnabled, resolveCapability, type CapabilityAdapter, type CapabilitySpec } from "../../capability/seam";
+import { warnCapabilityDegraded } from "../../capability/warn-once";
 import type { CallEdge, SymbolLayer, SymbolNode } from "../types";
 import { extractSymbolLayer, resolveCrossFileCalls, type TsNode } from "./extract";
 import {
@@ -65,6 +66,89 @@ export function createTreesitterSpec(
   };
 }
 
+// Compiled-binary fast path (T6, keryx-native-distribution).
+//
+// `bun build --compile` cannot statically trace `src/capability/seam.ts`'s
+// generic `await import(spec.optionalDependency)` (a runtime string variable —
+// oven-sh/bun#11732), so in a compiled binary gate 2 of `resolveCapability`
+// always throws for THIS capability even when `web-tree-sitter` is genuinely
+// bundled in. A LITERAL `await import("web-tree-sitter")` DOES bundle and work
+// in a compiled binary (verified empirically this flow).
+//
+// This function tries the literal import first. When it succeeds, it drives
+// the SAME gates the seam applies (1: manifest-enabled, 4: adapter build +
+// isAvailable, with the identical warn-once-on-degrade contract) — it only
+// replaces the ONE line that loads the dependency itself. When the literal
+// import throws (dependency genuinely not installed, e.g. a minimal npm
+// install without optional deps, or `bun run` dev mode where the package is
+// simply missing from node_modules), it falls through UNCHANGED to
+// `resolveCapability(cwd, spec)` — today's exact dev-mode behavior, including
+// the seam's own variable-based `await import(spec.optionalDependency)`
+// attempt and its warn-once messaging. `seam.ts` itself is never modified.
+async function loadTreesitterDepLiteral(): Promise<unknown | undefined> {
+  try {
+    return await import("web-tree-sitter");
+  } catch {
+    return undefined;
+  }
+}
+
+export async function resolveTreesitterCapability(
+  cwd: string,
+  config: TreesitterAdapterConfig,
+  resolve: (
+    cwd: string,
+    spec: CapabilitySpec<BuildInput, SymbolLayer>,
+  ) => Promise<CapabilityAdapter<BuildInput, SymbolLayer> | null> = resolveCapability,
+): Promise<CapabilityAdapter<BuildInput, SymbolLayer> | null> {
+  const spec = createTreesitterSpec(cwd, config);
+
+  try {
+    // Gate 1 FIRST — identical check the seam performs, no dep load, no
+    // warning when disabled (the normal default path per `seam.ts`'s own
+    // contract: "Disabled ⇒ null with NO dep load, NO asset touch, and NO
+    // warning"). This MUST run before the literal `import("web-tree-sitter")`
+    // below: with the check after, every `gdgraph build` call paid the
+    // literal-import cost even with the capability disabled — the bug this
+    // ordering fixes.
+    if (!(await isCapabilityEnabled(cwd, spec.id))) {
+      return null;
+    }
+
+    const literalDep = await loadTreesitterDepLiteral();
+    if (literalDep === undefined) {
+      // Literal import failed (dependency not actually installed) — defer to
+      // the seam's normal variable-based gate 2, unchanged. The seam
+      // re-checks gate 1, which is cheap and idempotent.
+      return await resolve(cwd, spec);
+    }
+
+    // Gate 2 replaced: the dependency is already loaded via the literal
+    // import above, so it is supplied directly instead of re-resolving
+    // `spec.optionalDependency` through the seam.
+    const adapter = spec.load({ dep: literalDep, asset: null });
+
+    // Gate 4: `isAvailable()` — same catch-and-degrade contract as the seam
+    // (AC0-8): a probe that throws degrades to the deterministic fallback.
+    let available: boolean;
+    try {
+      available = await adapter.isAvailable();
+    } catch {
+      warnCapabilityDegraded(spec.id, "adapter availability check threw");
+      return null;
+    }
+    if (!available) {
+      warnCapabilityDegraded(spec.id, "adapter reported unavailable");
+      return null;
+    }
+
+    return adapter;
+  } catch {
+    // Absolute backstop, mirrors the seam's own contract: never throw out.
+    return null;
+  }
+}
+
 class TreesitterAdapter implements CapabilityAdapter<BuildInput, SymbolLayer> {
   readonly id = "gdgraph.treesitter";
   private grammars: ResolvedGrammar[] = [];

package/src/gdskills/contracts/subagent-dispatch.schema.json

@@ -92,6 +92,46 @@
         "inherit": { "type": "boolean" }
       }
     },
+    "runtime": {
+      "description": "Which child runtime executes this dispatch (flow 176; docs/requirements/keryx-external-agent-runtime). Additive and optional: an absent block means the native keryx runtime, so every dispatch authored before this package stays valid. Constraints this schema cannot express — the agent resolving in the registry, the sandbox appearing in that agent's supported modes, and read-only versus allowed_actions — are enforced fail-closed by the pure validator in src/harness/external/dispatch.ts.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "description": "`keryx` runs the in-process agent loop; `external` spawns a vendor CLI subprocess.",
+          "type": "string",
+          "enum": ["keryx", "external"]
+        },
+        "agent": {
+          "description": "Registry id of the external agent. Required when kind is `external`.",
+          "type": "string",
+          "minLength": 1
+        },
+        "sandbox": {
+          "description": "Permission level for the external child. `worktree-write` is schema-valid but refused at runtime in the read-only release, with a reason distinguishable from an unsupported-by-this-agent refusal.",
+          "type": "string",
+          "enum": ["read-only", "worktree-write"]
+        },
+        "model": {
+          "description": "Model id passed to the external CLI. Omit or null to let the CLI resolve its own default under the operator's active subscription — keryx never pins a model the account may not be entitled to.",
+          "type": ["string", "null"],
+          "minLength": 1
+        },
+        "timeoutMs": { "type": ["integer", "null"], "minimum": 1000 },
+        "maxCostUnits": { "type": ["number", "null"], "exclusiveMinimum": 0 }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "kind": { "const": "external" } }, "required": ["kind"] },
+          "then": { "required": ["agent", "sandbox"] }
+        },
+        {
+          "if": { "properties": { "kind": { "const": "keryx" } }, "required": ["kind"] },
+          "then": { "not": { "required": ["agent"] } }
+        }
+      ]
+    },
     "provenance": {
       "type": "object",
       "additionalProperties": true,