@crewhaus/specialization-registry 0.1.4 → 0.1.6

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import { CrewhausError } from "@crewhaus/errors";
+export declare class SpecializationRegistryError extends CrewhausError {
+    readonly name = "SpecializationRegistryError";
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * One named invariant a specialization injects into a contract. The
+ * contract compiler maps each to a clause in the compiled YAML.
+ */
+export type Invariant = {
+    readonly id: string;
+    readonly description: string;
+    /** Severity for the contract reviewer: must-have vs nice-to-have. */
+    readonly required: boolean;
+};
+/**
+ * A specialization record. `keywords` are used by the default
+ * confidence-scoring heuristic; the score is the fraction of keywords
+ * present in the input text (case-insensitive substring match).
+ */
+export type Specialization = {
+    readonly name: string;
+    readonly description: string;
+    readonly keywords: ReadonlyArray<string>;
+    readonly invariants: ReadonlyArray<Invariant>;
+    /** Apply only when confidence >= this. Default 0.5. */
+    readonly confidenceThreshold: number;
+};
+export type SpecializationMatch = {
+    readonly specialization: Specialization;
+    readonly confidence: number;
+    /** Which keywords were hit; for audit + debugging. */
+    readonly matchedKeywords: ReadonlyArray<string>;
+};
+/**
+ * Built-in reference specializations. These are the ones the
+ * Meta-Engineering Harnesses paper specifically calls out as
+ * "recurring task domains" in their CTO-as-a-service deployment.
+ */
+export declare const BUILTIN_SPECIALIZATIONS: ReadonlyArray<Specialization>;
+/**
+ * Match a free-text issue/contract draft against the registered
+ * specializations. Returns the highest-confidence match whose score
+ * is >= its threshold, or undefined when no specialization matches.
+ *
+ * `mode: "strict"` skips auto-detection and only returns a match if
+ * the caller explicitly named one in `forceMatch`.
+ */
+export type MatchOptions = {
+    readonly mode?: "auto" | "strict";
+    readonly forceMatch?: string;
+    readonly registry?: ReadonlyArray<Specialization>;
+};
+export declare function match(text: string, opts?: MatchOptions): SpecializationMatch | undefined;
+/**
+ * Read JSON-encoded specialization records from a directory, merge
+ * them with the built-ins (overriding by `name`), and return the
+ * combined registry. Used by the contract compiler to pick up
+ * project-specific specializations from `.crewhaus/specializations/`.
+ */
+export declare function loadRegistry(dir: string): ReadonlyArray<Specialization>;

package/dist/index.js

@@ -0,0 +1,230 @@
+/**
+ * Track G (§58) — `specialization-registry`. File-backed registry of
+ * domain specializations.
+ *
+ * Source: Meta-Engineering Harnesses (Sengupta et al., HireNimbus,
+ * arxiv 2605.25665, §4.4). A specialization is a named collection of
+ * domain-specific invariants — for "payments" the invariants are
+ * idempotency keys, explicit state transitions, trust-boundary checks;
+ * for "auth" they're token expiry, scope checks, etc. The contract
+ * compiler (Track G in the same plan) calls into this registry to
+ * inject these invariants into the compiled contract.
+ *
+ * The paper's key safety rule: specializations apply only when
+ * **confidence crosses a threshold**. Below that, the pipeline
+ * proceeds without specialization to avoid corrupting the contract
+ * with wrong domain assumptions. The registry stores
+ * `(name, invariants, confidenceThreshold)` triples and exposes a
+ * `match(text, opts) → SpecializationMatch | undefined` function.
+ *
+ * v0 ships:
+ *   - In-memory registry seeded with three reference specializations
+ *     (payments, auth, booking).
+ *   - File-backed registry that reads from
+ *     `.crewhaus/specializations/<name>.json` (overrides built-ins).
+ *   - `match()` — keyword-based confidence scoring; the contract
+ *     compiler can pass `mode: "strict"` to require explicit opt-in
+ *     and skip auto-detection entirely.
+ *
+ * Cited paper: Meta-Engineering Harnesses (arxiv 2605.25665, §4.4).
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+export class SpecializationRegistryError extends CrewhausError {
+    name = "SpecializationRegistryError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+/**
+ * Built-in reference specializations. These are the ones the
+ * Meta-Engineering Harnesses paper specifically calls out as
+ * "recurring task domains" in their CTO-as-a-service deployment.
+ */
+export const BUILTIN_SPECIALIZATIONS = Object.freeze([
+    Object.freeze({
+        name: "payments",
+        description: "Stripe / payment intent flows. Idempotency, state transitions, trust boundaries.",
+        keywords: Object.freeze([
+            "stripe",
+            "payment",
+            "paymentintent",
+            "charge",
+            "refund",
+            "invoice",
+            "checkout",
+            "billing",
+        ]),
+        invariants: Object.freeze([
+            {
+                id: "idempotency-key",
+                description: "Every state-mutating request must carry an idempotency key; the handler must short-circuit on duplicate keys.",
+                required: true,
+            },
+            {
+                id: "state-transitions",
+                description: "Document the allowed state transitions explicitly (pending → succeeded, pending → failed, etc.) and reject any other transition.",
+                required: true,
+            },
+            {
+                id: "trust-boundary-client-status",
+                description: "Never trust client-reported payment status; always verify against the upstream provider.",
+                required: true,
+            },
+            {
+                id: "discount-deduction-source",
+                description: "Final-invoice calculations must read deposit/discount amounts from a single source of truth, not recompute from disparate fields.",
+                required: false,
+            },
+        ]),
+        confidenceThreshold: 0.3,
+    }),
+    Object.freeze({
+        name: "auth",
+        description: "Authentication and session-token handling. Token expiry, scope checks, revocation.",
+        keywords: Object.freeze([
+            "jwt",
+            "session",
+            "token",
+            "oauth",
+            "login",
+            "logout",
+            "refresh-token",
+            "auth",
+        ]),
+        invariants: Object.freeze([
+            {
+                id: "token-expiry-check",
+                description: "Every token verification must check expiry (exp claim) and reject expired tokens.",
+                required: true,
+            },
+            {
+                id: "scope-check",
+                description: "Every protected endpoint must verify the token's scope grants the requested action.",
+                required: true,
+            },
+            {
+                id: "revocation-list",
+                description: "Maintain a revocation list (or short token lifetimes + refresh tokens) so compromised tokens can be invalidated.",
+                required: true,
+            },
+        ]),
+        confidenceThreshold: 0.3,
+    }),
+    Object.freeze({
+        name: "booking",
+        description: "Scheduling / appointment flows. Conflict detection, time-zone handling, cancellation windows.",
+        keywords: Object.freeze([
+            "booking",
+            "appointment",
+            "schedule",
+            "calendar",
+            "reservation",
+            "slot",
+            "availability",
+        ]),
+        invariants: Object.freeze([
+            {
+                id: "conflict-detection",
+                description: "Reserving a slot must use a transaction that rejects double-bookings (FOR UPDATE / SELECT FOR SHARE / optimistic-lock).",
+                required: true,
+            },
+            {
+                id: "timezone-explicit",
+                description: "Every time field must carry its time zone (or be normalised to UTC) — never assume the server's local time.",
+                required: true,
+            },
+            {
+                id: "cancellation-window",
+                description: "Cancellations must respect a documented cancellation window; the handler enforces it server-side regardless of UI affordance.",
+                required: false,
+            },
+        ]),
+        confidenceThreshold: 0.3,
+    }),
+]);
+export function match(text, opts = {}) {
+    const registry = opts.registry ?? BUILTIN_SPECIALIZATIONS;
+    if (opts.mode === "strict") {
+        if (opts.forceMatch === undefined)
+            return undefined;
+        const spec = registry.find((s) => s.name === opts.forceMatch);
+        if (spec === undefined) {
+            throw new SpecializationRegistryError(`forceMatch "${opts.forceMatch}" not found in registry (known: ${registry
+                .map((s) => s.name)
+                .join(", ")})`);
+        }
+        return {
+            specialization: spec,
+            confidence: 1,
+            matchedKeywords: spec.keywords,
+        };
+    }
+    const lower = text.toLowerCase();
+    let best;
+    for (const spec of registry) {
+        const matched = [];
+        for (const kw of spec.keywords) {
+            if (lower.includes(kw.toLowerCase()))
+                matched.push(kw);
+        }
+        const confidence = spec.keywords.length === 0 ? 0 : matched.length / spec.keywords.length;
+        if (confidence >= spec.confidenceThreshold) {
+            if (best === undefined || confidence > best.confidence) {
+                best = { specialization: spec, confidence, matchedKeywords: matched };
+            }
+        }
+    }
+    return best;
+}
+/**
+ * Read JSON-encoded specialization records from a directory, merge
+ * them with the built-ins (overriding by `name`), and return the
+ * combined registry. Used by the contract compiler to pick up
+ * project-specific specializations from `.crewhaus/specializations/`.
+ */
+export function loadRegistry(dir) {
+    const abs = resolve(dir);
+    let entries;
+    try {
+        entries = readdirSync(abs);
+    }
+    catch {
+        return BUILTIN_SPECIALIZATIONS;
+    }
+    const overrides = {};
+    for (const name of entries) {
+        if (!name.endsWith(".json"))
+            continue;
+        const path = join(abs, name);
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch (err) {
+            throw new SpecializationRegistryError(`failed to parse ${path}: ${err.message}`);
+        }
+        const spec = parsed;
+        if (typeof spec.name !== "string" || spec.name.length === 0) {
+            throw new SpecializationRegistryError(`${path}: missing required "name" field`);
+        }
+        overrides[spec.name] = spec;
+    }
+    const merged = [];
+    const seen = new Set();
+    for (const builtin of BUILTIN_SPECIALIZATIONS) {
+        if (overrides[builtin.name] !== undefined) {
+            merged.push(overrides[builtin.name]);
+            seen.add(builtin.name);
+        }
+        else {
+            merged.push(builtin);
+        }
+    }
+    for (const [name, spec] of Object.entries(overrides)) {
+        if (!seen.has(name))
+            merged.push(spec);
+    }
+    return merged;
+}

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@crewhaus/specialization-registry",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "Track G / §58 — file-backed registry of domain specializations (payments, booking, auth) that inject invariants into contract compilation. Source: Meta-Engineering Harnesses (arxiv 2605.25665, §4.4).",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.4"
+    "@crewhaus/errors": "0.1.6"
   },
   "license": "Apache-2.0",
   "author": {
@@ -32,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,121 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { BUILTIN_SPECIALIZATIONS, SpecializationRegistryError, loadRegistry, match } from "./index";
-
-describe("BUILTIN_SPECIALIZATIONS", () => {
-  test("includes payments, auth, booking", () => {
-    const names = BUILTIN_SPECIALIZATIONS.map((s) => s.name);
-    expect(names).toContain("payments");
-    expect(names).toContain("auth");
-    expect(names).toContain("booking");
-  });
-
-  test("payments specialization names the four key invariants", () => {
-    const p = BUILTIN_SPECIALIZATIONS.find((s) => s.name === "payments");
-    const ids = p?.invariants.map((i) => i.id);
-    expect(ids).toContain("idempotency-key");
-    expect(ids).toContain("state-transitions");
-    expect(ids).toContain("trust-boundary-client-status");
-  });
-});
-
-describe("match (auto mode)", () => {
-  test("matches payments when text mentions Stripe + paymentintent + refund", () => {
-    const result = match("Implement Stripe paymentIntent flow with refund support and idempotency");
-    expect(result?.specialization.name).toBe("payments");
-    expect(result?.confidence).toBeGreaterThanOrEqual(0.3);
-  });
-
-  test("matches auth when text mentions jwt + login + token", () => {
-    const result = match("We need to add JWT-based login with refresh-token and revocation");
-    expect(result?.specialization.name).toBe("auth");
-  });
-
-  test("matches booking on appointment + slot + calendar", () => {
-    const result = match("Online booking with appointment slot calendar availability");
-    expect(result?.specialization.name).toBe("booking");
-  });
-
-  test("returns undefined when no specialization is confident enough", () => {
-    expect(match("Add a CSS spinner to the homepage")).toBeUndefined();
-  });
-
-  test("returns the highest-confidence specialization when multiple match", () => {
-    // Both auth and payments keywords; auth has more keyword density.
-    const result = match("session token jwt oauth refresh-token login logout stripe");
-    expect(result?.specialization.name).toBe("auth");
-  });
-});
-
-describe("match (strict mode)", () => {
-  test("returns named specialization with confidence 1 when forceMatch is set", () => {
-    const result = match("anything at all", { mode: "strict", forceMatch: "payments" });
-    expect(result?.specialization.name).toBe("payments");
-    expect(result?.confidence).toBe(1);
-  });
-
-  test("returns undefined when forceMatch is omitted in strict mode", () => {
-    expect(match("stripe refund paymentintent", { mode: "strict" })).toBeUndefined();
-  });
-
-  test("throws when forceMatch names an unknown specialization", () => {
-    expect(() => match("x", { mode: "strict", forceMatch: "nonexistent" })).toThrow(
-      SpecializationRegistryError,
-    );
-  });
-});
-
-describe("loadRegistry", () => {
-  let dir: string;
-  beforeEach(() => {
-    dir = mkdtempSync(join(tmpdir(), "spec-registry-test-"));
-  });
-  afterEach(() => {
-    rmSync(dir, { recursive: true, force: true });
-  });
-
-  test("returns built-ins when directory is empty", () => {
-    const r = loadRegistry(dir);
-    expect(r.length).toBe(BUILTIN_SPECIALIZATIONS.length);
-  });
-
-  test("returns built-ins when directory is missing", () => {
-    const r = loadRegistry(join(dir, "missing"));
-    expect(r.length).toBe(BUILTIN_SPECIALIZATIONS.length);
-  });
-
-  test("project-local files override built-ins by name", () => {
-    const override = {
-      name: "payments",
-      description: "custom payments",
-      keywords: ["stripe"],
-      invariants: [{ id: "x", description: "x", required: true }],
-      confidenceThreshold: 0.1,
-    };
-    writeFileSync(join(dir, "payments.json"), JSON.stringify(override));
-    const r = loadRegistry(dir);
-    const p = r.find((s) => s.name === "payments");
-    expect(p?.description).toBe("custom payments");
-    expect(p?.invariants.length).toBe(1);
-  });
-
-  test("project-local file with a new name is appended", () => {
-    const fresh = {
-      name: "ecommerce-checkout",
-      description: "new spec",
-      keywords: ["checkout", "cart"],
-      invariants: [{ id: "i", description: "i", required: true }],
-      confidenceThreshold: 0.5,
-    };
-    writeFileSync(join(dir, "ecommerce.json"), JSON.stringify(fresh));
-    const r = loadRegistry(dir);
-    expect(r.some((s) => s.name === "ecommerce-checkout")).toBe(true);
-  });
-
-  test("throws on malformed JSON", () => {
-    writeFileSync(join(dir, "bad.json"), "{this is not json}");
-    expect(() => loadRegistry(dir)).toThrow(SpecializationRegistryError);
-  });
-});

package/src/index.ts

@@ -1,287 +0,0 @@
-/**
- * Track G (§58) — `specialization-registry`. File-backed registry of
- * domain specializations.
- *
- * Source: Meta-Engineering Harnesses (Sengupta et al., HireNimbus,
- * arxiv 2605.25665, §4.4). A specialization is a named collection of
- * domain-specific invariants — for "payments" the invariants are
- * idempotency keys, explicit state transitions, trust-boundary checks;
- * for "auth" they're token expiry, scope checks, etc. The contract
- * compiler (Track G in the same plan) calls into this registry to
- * inject these invariants into the compiled contract.
- *
- * The paper's key safety rule: specializations apply only when
- * **confidence crosses a threshold**. Below that, the pipeline
- * proceeds without specialization to avoid corrupting the contract
- * with wrong domain assumptions. The registry stores
- * `(name, invariants, confidenceThreshold)` triples and exposes a
- * `match(text, opts) → SpecializationMatch | undefined` function.
- *
- * v0 ships:
- *   - In-memory registry seeded with three reference specializations
- *     (payments, auth, booking).
- *   - File-backed registry that reads from
- *     `.crewhaus/specializations/<name>.json` (overrides built-ins).
- *   - `match()` — keyword-based confidence scoring; the contract
- *     compiler can pass `mode: "strict"` to require explicit opt-in
- *     and skip auto-detection entirely.
- *
- * Cited paper: Meta-Engineering Harnesses (arxiv 2605.25665, §4.4).
- */
-import { readFileSync, readdirSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { CrewhausError } from "@crewhaus/errors";
-
-export class SpecializationRegistryError extends CrewhausError {
-  override readonly name = "SpecializationRegistryError";
-  constructor(message: string, cause?: unknown) {
-    super("config", message, cause);
-  }
-}
-
-/**
- * One named invariant a specialization injects into a contract. The
- * contract compiler maps each to a clause in the compiled YAML.
- */
-export type Invariant = {
-  readonly id: string;
-  readonly description: string;
-  /** Severity for the contract reviewer: must-have vs nice-to-have. */
-  readonly required: boolean;
-};
-
-/**
- * A specialization record. `keywords` are used by the default
- * confidence-scoring heuristic; the score is the fraction of keywords
- * present in the input text (case-insensitive substring match).
- */
-export type Specialization = {
-  readonly name: string;
-  readonly description: string;
-  readonly keywords: ReadonlyArray<string>;
-  readonly invariants: ReadonlyArray<Invariant>;
-  /** Apply only when confidence >= this. Default 0.5. */
-  readonly confidenceThreshold: number;
-};
-
-export type SpecializationMatch = {
-  readonly specialization: Specialization;
-  readonly confidence: number;
-  /** Which keywords were hit; for audit + debugging. */
-  readonly matchedKeywords: ReadonlyArray<string>;
-};
-
-/**
- * Built-in reference specializations. These are the ones the
- * Meta-Engineering Harnesses paper specifically calls out as
- * "recurring task domains" in their CTO-as-a-service deployment.
- */
-export const BUILTIN_SPECIALIZATIONS: ReadonlyArray<Specialization> = Object.freeze([
-  Object.freeze({
-    name: "payments",
-    description: "Stripe / payment intent flows. Idempotency, state transitions, trust boundaries.",
-    keywords: Object.freeze([
-      "stripe",
-      "payment",
-      "paymentintent",
-      "charge",
-      "refund",
-      "invoice",
-      "checkout",
-      "billing",
-    ]),
-    invariants: Object.freeze([
-      {
-        id: "idempotency-key",
-        description:
-          "Every state-mutating request must carry an idempotency key; the handler must short-circuit on duplicate keys.",
-        required: true,
-      },
-      {
-        id: "state-transitions",
-        description:
-          "Document the allowed state transitions explicitly (pending → succeeded, pending → failed, etc.) and reject any other transition.",
-        required: true,
-      },
-      {
-        id: "trust-boundary-client-status",
-        description:
-          "Never trust client-reported payment status; always verify against the upstream provider.",
-        required: true,
-      },
-      {
-        id: "discount-deduction-source",
-        description:
-          "Final-invoice calculations must read deposit/discount amounts from a single source of truth, not recompute from disparate fields.",
-        required: false,
-      },
-    ]),
-    confidenceThreshold: 0.3,
-  }),
-  Object.freeze({
-    name: "auth",
-    description:
-      "Authentication and session-token handling. Token expiry, scope checks, revocation.",
-    keywords: Object.freeze([
-      "jwt",
-      "session",
-      "token",
-      "oauth",
-      "login",
-      "logout",
-      "refresh-token",
-      "auth",
-    ]),
-    invariants: Object.freeze([
-      {
-        id: "token-expiry-check",
-        description:
-          "Every token verification must check expiry (exp claim) and reject expired tokens.",
-        required: true,
-      },
-      {
-        id: "scope-check",
-        description:
-          "Every protected endpoint must verify the token's scope grants the requested action.",
-        required: true,
-      },
-      {
-        id: "revocation-list",
-        description:
-          "Maintain a revocation list (or short token lifetimes + refresh tokens) so compromised tokens can be invalidated.",
-        required: true,
-      },
-    ]),
-    confidenceThreshold: 0.3,
-  }),
-  Object.freeze({
-    name: "booking",
-    description:
-      "Scheduling / appointment flows. Conflict detection, time-zone handling, cancellation windows.",
-    keywords: Object.freeze([
-      "booking",
-      "appointment",
-      "schedule",
-      "calendar",
-      "reservation",
-      "slot",
-      "availability",
-    ]),
-    invariants: Object.freeze([
-      {
-        id: "conflict-detection",
-        description:
-          "Reserving a slot must use a transaction that rejects double-bookings (FOR UPDATE / SELECT FOR SHARE / optimistic-lock).",
-        required: true,
-      },
-      {
-        id: "timezone-explicit",
-        description:
-          "Every time field must carry its time zone (or be normalised to UTC) — never assume the server's local time.",
-        required: true,
-      },
-      {
-        id: "cancellation-window",
-        description:
-          "Cancellations must respect a documented cancellation window; the handler enforces it server-side regardless of UI affordance.",
-        required: false,
-      },
-    ]),
-    confidenceThreshold: 0.3,
-  }),
-]);
-
-/**
- * Match a free-text issue/contract draft against the registered
- * specializations. Returns the highest-confidence match whose score
- * is >= its threshold, or undefined when no specialization matches.
- *
- * `mode: "strict"` skips auto-detection and only returns a match if
- * the caller explicitly named one in `forceMatch`.
- */
-export type MatchOptions = {
-  readonly mode?: "auto" | "strict";
-  readonly forceMatch?: string;
-  readonly registry?: ReadonlyArray<Specialization>;
-};
-
-export function match(text: string, opts: MatchOptions = {}): SpecializationMatch | undefined {
-  const registry = opts.registry ?? BUILTIN_SPECIALIZATIONS;
-  if (opts.mode === "strict") {
-    if (opts.forceMatch === undefined) return undefined;
-    const spec = registry.find((s) => s.name === opts.forceMatch);
-    if (spec === undefined) {
-      throw new SpecializationRegistryError(
-        `forceMatch "${opts.forceMatch}" not found in registry (known: ${registry
-          .map((s) => s.name)
-          .join(", ")})`,
-      );
-    }
-    return {
-      specialization: spec,
-      confidence: 1,
-      matchedKeywords: spec.keywords,
-    };
-  }
-  const lower = text.toLowerCase();
-  let best: SpecializationMatch | undefined;
-  for (const spec of registry) {
-    const matched: string[] = [];
-    for (const kw of spec.keywords) {
-      if (lower.includes(kw.toLowerCase())) matched.push(kw);
-    }
-    const confidence = spec.keywords.length === 0 ? 0 : matched.length / spec.keywords.length;
-    if (confidence >= spec.confidenceThreshold) {
-      if (best === undefined || confidence > best.confidence) {
-        best = { specialization: spec, confidence, matchedKeywords: matched };
-      }
-    }
-  }
-  return best;
-}
-
-/**
- * Read JSON-encoded specialization records from a directory, merge
- * them with the built-ins (overriding by `name`), and return the
- * combined registry. Used by the contract compiler to pick up
- * project-specific specializations from `.crewhaus/specializations/`.
- */
-export function loadRegistry(dir: string): ReadonlyArray<Specialization> {
-  const abs = resolve(dir);
-  let entries: string[];
-  try {
-    entries = readdirSync(abs);
-  } catch {
-    return BUILTIN_SPECIALIZATIONS;
-  }
-  const overrides: Record<string, Specialization> = {};
-  for (const name of entries) {
-    if (!name.endsWith(".json")) continue;
-    const path = join(abs, name);
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(readFileSync(path, "utf8"));
-    } catch (err) {
-      throw new SpecializationRegistryError(`failed to parse ${path}: ${(err as Error).message}`);
-    }
-    const spec = parsed as Specialization;
-    if (typeof spec.name !== "string" || spec.name.length === 0) {
-      throw new SpecializationRegistryError(`${path}: missing required "name" field`);
-    }
-    overrides[spec.name] = spec;
-  }
-  const merged: Specialization[] = [];
-  const seen = new Set<string>();
-  for (const builtin of BUILTIN_SPECIALIZATIONS) {
-    if (overrides[builtin.name] !== undefined) {
-      merged.push(overrides[builtin.name] as Specialization);
-      seen.add(builtin.name);
-    } else {
-      merged.push(builtin);
-    }
-  }
-  for (const [name, spec] of Object.entries(overrides)) {
-    if (!seen.has(name)) merged.push(spec);
-  }
-  return merged;
-}