@crewhaus/spec-patch 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Pillar 2 — `spec-patch`. The structured mutation primitive that the
+ * active eval optimizer uses to translate "the prompt that scored higher"
+ * back into a YAML edit the user can review, commit, and re-run.
+ *
+ * Why patch the SPEC (not the IR)?
+ *
+ * The compiler does destructive normalisation in `lower()`: sub-agent
+ * maps become arrays, role names get alphabetically sorted, secrets get
+ * rewritten to env-var refs via `lowerSecret`, permission rules get
+ * de-duped and re-ordered. The IR is intentionally lossy and ordering-
+ * canonical because its job is to feed codegen, not round-trip to YAML.
+ *
+ * A patch at the IR layer therefore can't write back to YAML — there's
+ * no path from a frozen sorted array back to the source-author's map
+ * with their comments and field ordering. Patching at the SPEC layer
+ * (i.e. the YAML AST) keeps the round-trip honest: a `crewhaus optimize
+ * --write-back` rewrites the user's file with their comments preserved
+ * and only the touched values changed.
+ *
+ * The `yaml` package's `parseDocument` gives us the CST we need. The
+ * Document API has `setIn(path, value)`, `getIn(path)`, `deleteIn(path)`
+ * that operate on the live AST; `toString()` renders back with comment
+ * and key-order fidelity.
+ *
+ * IR-passes (in `@crewhaus/ir-passes`) stay what they are — codegen-
+ * time optimisations that run AFTER lowering. They don't get conflated
+ * with eval-driven mutation. The two systems share nothing; that's
+ * intentional.
+ *
+ * Catalog layer: F2 (compiler periphery). Brief: 278.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { type Spec } from "@crewhaus/spec";
+export declare class SpecPatchError extends CrewhausError {
+    readonly name = "SpecPatchError";
+    constructor(message: string, cause?: unknown);
+}
+export type SpecPatchOp = "replace" | "add" | "remove";
+/**
+ * A structured edit to a spec. `path` is a property-key chain (no array
+ * indices today — the spec's mutation surface is all object fields). The
+ * `target` discriminator must match the spec being patched; the validator
+ * refuses cross-target patches so an optimizer can't pass an `IrCli`
+ * patch to a `pipeline` spec.
+ */
+export type SpecPatch = {
+    readonly target: Spec["target"];
+    readonly path: ReadonlyArray<string>;
+    readonly op: SpecPatchOp;
+    /** Required for `"replace"` and `"add"`; ignored for `"remove"`. */
+    readonly value?: unknown;
+    /**
+     * Optional rationale string for audit / write-back commit messages.
+     * The optimizer fills this with the mutation kind + observed delta.
+     */
+    readonly rationale?: string;
+};
+export type ApplySpecPatchResult = {
+    /** The mutated YAML text, with comments and key order preserved. */
+    readonly yaml: string;
+    /** The re-parsed Spec after the patch. */
+    readonly spec: Spec;
+};
+/**
+ * Apply a structured patch to a YAML spec source. Uses the `yaml`
+ * package's CST so comments and key order survive the round-trip; the
+ * only bytes that change are the ones the patch targets.
+ *
+ * Validates the resulting document against the Spec schema; throws
+ * `SpecPatchError` if the mutation produces invalid spec.
+ */
+export declare function applySpecPatch(yamlText: string, patch: SpecPatch): ApplySpecPatchResult;
+/**
+ * Type-check a patch against a parsed Spec WITHOUT applying it. Used
+ * by the optimizer to refuse cross-target patches and patches that
+ * reference paths outside the optimisation surface.
+ *
+ * The path-validity check is the "soft" version: it verifies the path
+ * is structurally reachable (each segment names a defined field). It
+ * does NOT instantiate the patched value — `applySpecPatch` does that
+ * via `parseSpec`.
+ */
+export declare function validatePatch(spec: Spec, patch: SpecPatch): void;
+/**
+ * Per-target whitelist of mutation paths the active optimizer is
+ * allowed to touch. Adding a new field here is the explicit signal that
+ * it's safe to autotune. Skipping this list means the optimizer can
+ * only mutate prompts (the default), preserving the "spec safety floor"
+ * that an optimizer can't accidentally rewrite security-critical fields
+ * like `permissions.mode` or `model_router` rules.
+ */
+export declare const OPTIMIZABLE_PATHS: Readonly<Record<Spec["target"], ReadonlyArray<ReadonlyArray<string>>>>;
+/**
+ * Format a YAML header comment to prepend to a written-back file. The
+ * orchestrator's `--write-back` writes this above the original spec so
+ * a human reviewer can see when and by what an optimisation pass ran.
+ */
+export declare function formatWriteBackHeader(opts: {
+    readonly runId: string;
+    readonly mutator: string;
+    readonly scoreBefore: number;
+    readonly scoreAfter: number;
+    readonly iterations: number;
+    readonly timestamp?: string;
+}): string;

package/dist/index.js

@@ -0,0 +1,294 @@
+/**
+ * Pillar 2 — `spec-patch`. The structured mutation primitive that the
+ * active eval optimizer uses to translate "the prompt that scored higher"
+ * back into a YAML edit the user can review, commit, and re-run.
+ *
+ * Why patch the SPEC (not the IR)?
+ *
+ * The compiler does destructive normalisation in `lower()`: sub-agent
+ * maps become arrays, role names get alphabetically sorted, secrets get
+ * rewritten to env-var refs via `lowerSecret`, permission rules get
+ * de-duped and re-ordered. The IR is intentionally lossy and ordering-
+ * canonical because its job is to feed codegen, not round-trip to YAML.
+ *
+ * A patch at the IR layer therefore can't write back to YAML — there's
+ * no path from a frozen sorted array back to the source-author's map
+ * with their comments and field ordering. Patching at the SPEC layer
+ * (i.e. the YAML AST) keeps the round-trip honest: a `crewhaus optimize
+ * --write-back` rewrites the user's file with their comments preserved
+ * and only the touched values changed.
+ *
+ * The `yaml` package's `parseDocument` gives us the CST we need. The
+ * Document API has `setIn(path, value)`, `getIn(path)`, `deleteIn(path)`
+ * that operate on the live AST; `toString()` renders back with comment
+ * and key-order fidelity.
+ *
+ * IR-passes (in `@crewhaus/ir-passes`) stay what they are — codegen-
+ * time optimisations that run AFTER lowering. They don't get conflated
+ * with eval-driven mutation. The two systems share nothing; that's
+ * intentional.
+ *
+ * Catalog layer: F2 (compiler periphery). Brief: 278.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { parseSpec } from "@crewhaus/spec";
+import { parseDocument } from "yaml";
+import { z } from "zod";
+export class SpecPatchError extends CrewhausError {
+    name = "SpecPatchError";
+    constructor(message, cause) {
+        super("compiler", message, cause);
+    }
+}
+const specPatchSchema = z.object({
+    target: z.string().min(1),
+    path: z.array(z.string().min(1)).min(1),
+    op: z.enum(["replace", "add", "remove"]),
+    value: z.unknown().optional(),
+    rationale: z.string().optional(),
+});
+/**
+ * Apply a structured patch to a YAML spec source. Uses the `yaml`
+ * package's CST so comments and key order survive the round-trip; the
+ * only bytes that change are the ones the patch targets.
+ *
+ * Validates the resulting document against the Spec schema; throws
+ * `SpecPatchError` if the mutation produces invalid spec.
+ */
+export function applySpecPatch(yamlText, patch) {
+    const parsed = specPatchSchema.safeParse(patch);
+    if (!parsed.success) {
+        throw new SpecPatchError(`patch shape is invalid: ${parsed.error.message}`);
+    }
+    let doc;
+    try {
+        doc = parseDocument(yamlText);
+    }
+    catch (err) {
+        throw new SpecPatchError("input YAML is not parseable", err);
+    }
+    // Verify the patch matches the spec's target. Cheap pre-check so we
+    // fail with a useful message before the Zod validation later.
+    const docTarget = doc.getIn(["target"]);
+    if (typeof docTarget === "string" && docTarget !== patch.target) {
+        throw new SpecPatchError(`patch target "${patch.target}" does not match spec target "${docTarget}"`);
+    }
+    const path = [...patch.path];
+    switch (patch.op) {
+        case "replace": {
+            if (!doc.hasIn(path)) {
+                throw new SpecPatchError(`cannot replace ${formatPath(path)}: path does not exist`);
+            }
+            doc.setIn(path, patch.value);
+            break;
+        }
+        case "add": {
+            if (doc.hasIn(path)) {
+                throw new SpecPatchError(`cannot add ${formatPath(path)}: path already exists (use "replace")`);
+            }
+            doc.setIn(path, patch.value);
+            break;
+        }
+        case "remove": {
+            if (!doc.hasIn(path)) {
+                throw new SpecPatchError(`cannot remove ${formatPath(path)}: path does not exist`);
+            }
+            doc.deleteIn(path);
+            break;
+        }
+    }
+    const newYaml = doc.toString();
+    let spec;
+    try {
+        spec = parseSpec(newYaml);
+    }
+    catch (err) {
+        throw new SpecPatchError(`patched YAML failed spec validation: ${err.message}`, err);
+    }
+    return { yaml: newYaml, spec };
+}
+/**
+ * Type-check a patch against a parsed Spec WITHOUT applying it. Used
+ * by the optimizer to refuse cross-target patches and patches that
+ * reference paths outside the optimisation surface.
+ *
+ * The path-validity check is the "soft" version: it verifies the path
+ * is structurally reachable (each segment names a defined field). It
+ * does NOT instantiate the patched value — `applySpecPatch` does that
+ * via `parseSpec`.
+ */
+export function validatePatch(spec, patch) {
+    const parsed = specPatchSchema.safeParse(patch);
+    if (!parsed.success) {
+        throw new SpecPatchError(`patch shape is invalid: ${parsed.error.message}`);
+    }
+    if (patch.target !== spec.target) {
+        throw new SpecPatchError(`patch target "${patch.target}" does not match spec target "${spec.target}"`);
+    }
+    if (!isOptimizable(spec.target, patch.path)) {
+        throw new SpecPatchError(`path ${formatPath(patch.path)} is not listed in OPTIMIZABLE_PATHS for target "${spec.target}"; add it to packages/spec-patch/src/index.ts if it's intended to be tunable`);
+    }
+}
+function formatPath(path) {
+    return path.join(".");
+}
+/**
+ * Per-target whitelist of mutation paths the active optimizer is
+ * allowed to touch. Adding a new field here is the explicit signal that
+ * it's safe to autotune. Skipping this list means the optimizer can
+ * only mutate prompts (the default), preserving the "spec safety floor"
+ * that an optimizer can't accidentally rewrite security-critical fields
+ * like `permissions.mode` or `model_router` rules.
+ */
+export const OPTIMIZABLE_PATHS = Object.freeze({
+    cli: Object.freeze([
+        Object.freeze(["agent", "instructions"]),
+        Object.freeze(["failure_taxonomy"]),
+        Object.freeze(["compaction", "threshold"]),
+        // Pillar 2 active context curation — eval-optimizer can flip the
+        // semantic-dedupe + relevance-reorder pass on/off and tune its
+        // similarity threshold, which dominates input-token cost on long runs.
+        Object.freeze(["compaction", "curate"]),
+        Object.freeze(["compaction", "dedupeThreshold"]),
+        Object.freeze(["compaction", "relevanceTopK"]),
+        // Pillar 3 sink-side fabric — egress policy + intent-gate thresholds
+        // are tunable so the eval-optimizer can find the sweet spot between
+        // false-positive denials and false-negative exfil bypasses.
+        Object.freeze(["security", "egressPolicy"]),
+        Object.freeze(["security", "justification"]),
+        // §47 blockchain subsystem (slice 0). Whole-block replacement so the
+        // optimizer can tune `chains[*].finality.count`, `chains[*].rpcPolicy`,
+        // `transaction_policy.maxValueWei`, and `transaction_policy.simulationRequired`
+        // by patching their parent block.
+        Object.freeze(["chains"]),
+        Object.freeze(["transaction_policy"]),
+    ]),
+    workflow: Object.freeze([
+        Object.freeze(["steps"]),
+        Object.freeze(["failure_taxonomy"]),
+        Object.freeze(["chains"]),
+        Object.freeze(["transaction_policy"]),
+    ]) /* whole-step replacement allowed */,
+    channel: Object.freeze([
+        Object.freeze(["agent", "instructions"]),
+        Object.freeze(["failure_taxonomy"]),
+        Object.freeze(["chains"]),
+        Object.freeze(["transaction_policy"]),
+    ]),
+    graph: Object.freeze([
+        Object.freeze(["nodes"]),
+        Object.freeze(["failure_taxonomy"]),
+        Object.freeze(["chains"]),
+        Object.freeze(["transaction_policy"]),
+    ]),
+    managed: Object.freeze([
+        Object.freeze(["agent", "instructions"]),
+        Object.freeze(["failure_taxonomy"]),
+    ]),
+    pipeline: Object.freeze([
+        Object.freeze(["agent", "instructions"]),
+        Object.freeze(["failure_taxonomy"]),
+        Object.freeze(["indexing", "chunkSize"]),
+        Object.freeze(["indexing", "chunkOverlap"]),
+        Object.freeze(["retrieve", "defaultK"]),
+    ]),
+    crew: Object.freeze([
+        Object.freeze(["roles"]),
+        Object.freeze(["failure_taxonomy"]),
+        Object.freeze(["chains"]),
+        Object.freeze(["transaction_policy"]),
+    ]) /* whole-role replacement */,
+    research: Object.freeze([
+        Object.freeze(["agent", "instructions"]),
+        Object.freeze(["failure_taxonomy"]),
+        Object.freeze(["retrieve", "maxDepth"]),
+        Object.freeze(["chains"]),
+        Object.freeze(["transaction_policy"]),
+    ]),
+    batch: Object.freeze([
+        Object.freeze(["agent", "instructions"]),
+        Object.freeze(["failure_taxonomy"]),
+        Object.freeze(["chains"]),
+        Object.freeze(["transaction_policy"]),
+    ]),
+    voice: Object.freeze([
+        Object.freeze(["agent", "instructions"]),
+        Object.freeze(["failure_taxonomy"]),
+    ]),
+    browser: Object.freeze([
+        Object.freeze(["agent", "instructions"]),
+        Object.freeze(["failure_taxonomy"]),
+    ]),
+    eval: Object.freeze([
+        Object.freeze(["agent", "instructions"]),
+        Object.freeze(["failure_taxonomy"]),
+    ]),
+    // §47 onchain daemon: full cross-cutting blocks are optimizable.
+    onchain: Object.freeze([
+        Object.freeze(["agent", "instructions"]),
+        Object.freeze(["failure_taxonomy"]),
+        Object.freeze(["chains"]),
+        Object.freeze(["triggers"]),
+        Object.freeze(["transaction_policy"]),
+        Object.freeze(["idempotencyWindowMs"]),
+    ]),
+    // §47 onchain-game: instructions, game.objective, and the policy are
+    // the productive knobs; move-timeout-ms is the realtime quality knob.
+    "onchain-game": Object.freeze([
+        Object.freeze(["agent", "instructions"]),
+        Object.freeze(["failure_taxonomy"]),
+        Object.freeze(["game"]),
+        Object.freeze(["transaction_policy"]),
+    ]),
+});
+function isOptimizable(target, path) {
+    const allowed = OPTIMIZABLE_PATHS[target];
+    for (const ok of allowed) {
+        if (ok.length !== path.length)
+            continue;
+        let match = true;
+        for (let i = 0; i < ok.length; i++) {
+            if (ok[i] !== path[i]) {
+                match = false;
+                break;
+            }
+        }
+        if (match)
+            return true;
+    }
+    // Allow patches with a prefix that matches an optimizable path
+    // (e.g. `["nodes", "0", "instructions"]` if `["nodes"]` is whitelisted)
+    // so the optimizer can do fine-grained updates without listing every
+    // sub-path.
+    for (const ok of allowed) {
+        if (path.length < ok.length)
+            continue;
+        let match = true;
+        for (let i = 0; i < ok.length; i++) {
+            if (ok[i] !== path[i]) {
+                match = false;
+                break;
+            }
+        }
+        if (match)
+            return true;
+    }
+    return false;
+}
+/**
+ * Format a YAML header comment to prepend to a written-back file. The
+ * orchestrator's `--write-back` writes this above the original spec so
+ * a human reviewer can see when and by what an optimisation pass ran.
+ */
+export function formatWriteBackHeader(opts) {
+    const ts = opts.timestamp ?? new Date().toISOString();
+    const delta = (opts.scoreAfter - opts.scoreBefore).toFixed(3);
+    return [
+        `# crewhaus optimize: runId ${opts.runId}`,
+        `# - mutator: ${opts.mutator}`,
+        `# - iterations: ${opts.iterations}`,
+        `# - score: ${opts.scoreBefore.toFixed(3)} → ${opts.scoreAfter.toFixed(3)} (Δ ${delta})`,
+        `# - generated: ${ts}`,
+        "",
+    ].join("\n");
+}

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "@crewhaus/spec-patch",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Pillar-2 patch infrastructure — apply a SpecPatch to a YAML source preserving comments and key order via the yaml CST. Drives the active eval optimizer's spec-level mutation loop.",
-  "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.3",
-    "@crewhaus/spec": "0.1.3",
+    "@crewhaus/errors": "0.1.5",
+    "@crewhaus/spec": "0.1.5",
     "yaml": "^2.6.0",
     "zod": "^3.23.8"
   },
@@ -35,5 +38,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,236 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { OPTIMIZABLE_PATHS, applySpecPatch, formatWriteBackHeader, validatePatch } from "./index";
-
-const CLI_YAML = `# A simple CLI agent
-target: cli
-name: hello-cli
-agent:
-  model: claude-sonnet-4-5
-  # The system prompt the model sees on every turn:
-  instructions: You are a helpful assistant.
-tools:
-  - Read
-  - Write
-`;
-
-const PIPELINE_YAML = `target: pipeline
-name: hello-rag
-agent:
-  model: claude-sonnet-4-5
-  instructions: Answer using only the retrieved docs.
-retrieve:
-  embedderModel: text-embedding-3-small
-  defaultK: 3
-indexing:
-  # Default chunking — deliberately short for testing
-  chunkSize: 200
-  chunkOverlap: 20
-  documents:
-    - id: doc1
-      text: The capital of France is Paris.
-`;
-
-describe("applySpecPatch — round-trip", () => {
-  test("replaces agent.instructions and re-parses", () => {
-    const patch = {
-      target: "cli" as const,
-      path: ["agent", "instructions"] as const,
-      op: "replace" as const,
-      value: "Think step by step before answering.",
-    };
-    const { yaml, spec } = applySpecPatch(CLI_YAML, patch);
-    if (spec.target !== "cli") throw new Error("expected cli spec");
-    expect(spec.agent.instructions).toBe("Think step by step before answering.");
-    expect(yaml).toContain("instructions: Think step by step before answering.");
-  });
-
-  test("preserves leading comments and structural comments", () => {
-    const patch = {
-      target: "cli" as const,
-      path: ["agent", "instructions"] as const,
-      op: "replace" as const,
-      value: "Be concise.",
-    };
-    const { yaml } = applySpecPatch(CLI_YAML, patch);
-    expect(yaml).toContain("# A simple CLI agent");
-    expect(yaml).toContain("# The system prompt the model sees on every turn");
-  });
-
-  test("replaces a numeric field on a pipeline spec", () => {
-    const patch = {
-      target: "pipeline" as const,
-      path: ["indexing", "chunkOverlap"] as const,
-      op: "replace" as const,
-      value: 50,
-    };
-    const { yaml, spec } = applySpecPatch(PIPELINE_YAML, patch);
-    if (spec.target !== "pipeline") throw new Error("expected pipeline spec");
-    expect(spec.indexing.chunkOverlap).toBe(50);
-    expect(yaml).toContain("chunkOverlap: 50");
-    // Comment on indexing block survives
-    expect(yaml).toContain("# Default chunking — deliberately short for testing");
-  });
-});
-
-describe("applySpecPatch — error cases", () => {
-  test("cross-target patch is rejected with a clear error", () => {
-    expect(() =>
-      applySpecPatch(CLI_YAML, {
-        target: "pipeline",
-        path: ["agent", "instructions"],
-        op: "replace",
-        value: "x",
-      }),
-    ).toThrow(/does not match spec target/);
-  });
-
-  test("non-existent replace path is rejected", () => {
-    expect(() =>
-      applySpecPatch(CLI_YAML, {
-        target: "cli",
-        path: ["agent", "nonexistent_field"],
-        op: "replace",
-        value: "x",
-      }),
-    ).toThrow(/path does not exist/);
-  });
-
-  test("add to an existing path is rejected", () => {
-    expect(() =>
-      applySpecPatch(CLI_YAML, {
-        target: "cli",
-        path: ["agent", "instructions"],
-        op: "add",
-        value: "x",
-      }),
-    ).toThrow(/path already exists/);
-  });
-
-  test("remove a non-existent path is rejected", () => {
-    expect(() =>
-      applySpecPatch(CLI_YAML, {
-        target: "cli",
-        path: ["agent", "nope"],
-        op: "remove",
-      }),
-    ).toThrow(/path does not exist/);
-  });
-
-  test("invalid patch shape (empty path array) is rejected", () => {
-    expect(() =>
-      applySpecPatch(CLI_YAML, {
-        target: "cli",
-        // biome-ignore lint/suspicious/noExplicitAny: testing runtime validation
-        path: [] as any,
-        op: "replace",
-        value: "x",
-      }),
-    ).toThrow(/patch shape is invalid/);
-  });
-
-  test("patched YAML that breaks spec schema is rejected", () => {
-    // Replacing model with a non-string number should be rejected.
-    expect(() =>
-      applySpecPatch(CLI_YAML, {
-        target: "cli",
-        path: ["agent", "model"],
-        op: "replace",
-        value: 42,
-      }),
-    ).toThrow(/spec validation failed/);
-  });
-});
-
-describe("validatePatch", () => {
-  test("accepts a whitelisted optimizable path", () => {
-    const { spec } = applySpecPatch(PIPELINE_YAML, {
-      target: "pipeline",
-      path: ["indexing", "chunkOverlap"],
-      op: "replace",
-      value: 30,
-    });
-    expect(() =>
-      validatePatch(spec, {
-        target: "pipeline",
-        path: ["indexing", "chunkOverlap"],
-        op: "replace",
-        value: 40,
-      }),
-    ).not.toThrow();
-  });
-
-  test("rejects a path that's not in OPTIMIZABLE_PATHS", () => {
-    const { spec } = applySpecPatch(CLI_YAML, {
-      target: "cli",
-      path: ["agent", "instructions"],
-      op: "replace",
-      value: "x",
-    });
-    expect(() =>
-      validatePatch(spec, {
-        target: "cli",
-        path: ["agent", "model"], // intentionally not in cli's OPTIMIZABLE_PATHS
-        op: "replace",
-        value: "opus-4",
-      }),
-    ).toThrow(/not listed in OPTIMIZABLE_PATHS/);
-  });
-
-  test("cross-target patch is rejected before path-check", () => {
-    const { spec } = applySpecPatch(CLI_YAML, {
-      target: "cli",
-      path: ["agent", "instructions"],
-      op: "replace",
-      value: "x",
-    });
-    expect(() =>
-      validatePatch(spec, {
-        target: "pipeline",
-        path: ["agent", "instructions"],
-        op: "replace",
-        value: "y",
-      }),
-    ).toThrow(/does not match spec target/);
-  });
-});
-
-describe("OPTIMIZABLE_PATHS", () => {
-  test("every shipped target shape has at least one whitelisted path", () => {
-    const targets = [
-      "cli",
-      "workflow",
-      "channel",
-      "graph",
-      "managed",
-      "pipeline",
-      "crew",
-      "research",
-      "batch",
-      "voice",
-      "browser",
-      "eval",
-    ] as const;
-    for (const t of targets) {
-      expect(OPTIMIZABLE_PATHS[t]).toBeDefined();
-      expect(OPTIMIZABLE_PATHS[t].length).toBeGreaterThanOrEqual(1);
-    }
-  });
-});
-
-describe("formatWriteBackHeader", () => {
-  test("produces a deterministic header given a fixed timestamp", () => {
-    const header = formatWriteBackHeader({
-      runId: "opt_abc123",
-      mutator: "rule-based",
-      scoreBefore: 0.45,
-      scoreAfter: 0.78,
-      iterations: 12,
-      timestamp: "2026-05-10T12:00:00Z",
-    });
-    expect(header).toContain("runId opt_abc123");
-    expect(header).toContain("mutator: rule-based");
-    expect(header).toContain("iterations: 12");
-    expect(header).toContain("score: 0.450 → 0.780 (Δ 0.330)");
-    expect(header).toContain("2026-05-10T12:00:00Z");
-  });
-});

package/src/index.ts

@@ -1,344 +0,0 @@
-/**
- * Pillar 2 — `spec-patch`. The structured mutation primitive that the
- * active eval optimizer uses to translate "the prompt that scored higher"
- * back into a YAML edit the user can review, commit, and re-run.
- *
- * Why patch the SPEC (not the IR)?
- *
- * The compiler does destructive normalisation in `lower()`: sub-agent
- * maps become arrays, role names get alphabetically sorted, secrets get
- * rewritten to env-var refs via `lowerSecret`, permission rules get
- * de-duped and re-ordered. The IR is intentionally lossy and ordering-
- * canonical because its job is to feed codegen, not round-trip to YAML.
- *
- * A patch at the IR layer therefore can't write back to YAML — there's
- * no path from a frozen sorted array back to the source-author's map
- * with their comments and field ordering. Patching at the SPEC layer
- * (i.e. the YAML AST) keeps the round-trip honest: a `crewhaus optimize
- * --write-back` rewrites the user's file with their comments preserved
- * and only the touched values changed.
- *
- * The `yaml` package's `parseDocument` gives us the CST we need. The
- * Document API has `setIn(path, value)`, `getIn(path)`, `deleteIn(path)`
- * that operate on the live AST; `toString()` renders back with comment
- * and key-order fidelity.
- *
- * IR-passes (in `@crewhaus/ir-passes`) stay what they are — codegen-
- * time optimisations that run AFTER lowering. They don't get conflated
- * with eval-driven mutation. The two systems share nothing; that's
- * intentional.
- *
- * Catalog layer: F2 (compiler periphery). Brief: 278.
- */
-import { CrewhausError } from "@crewhaus/errors";
-import { type Spec, parseSpec } from "@crewhaus/spec";
-import { parseDocument } from "yaml";
-import { z } from "zod";
-
-export class SpecPatchError extends CrewhausError {
-  override readonly name = "SpecPatchError";
-  constructor(message: string, cause?: unknown) {
-    super("compiler", message, cause);
-  }
-}
-
-export type SpecPatchOp = "replace" | "add" | "remove";
-
-/**
- * A structured edit to a spec. `path` is a property-key chain (no array
- * indices today — the spec's mutation surface is all object fields). The
- * `target` discriminator must match the spec being patched; the validator
- * refuses cross-target patches so an optimizer can't pass an `IrCli`
- * patch to a `pipeline` spec.
- */
-export type SpecPatch = {
-  readonly target: Spec["target"];
-  readonly path: ReadonlyArray<string>;
-  readonly op: SpecPatchOp;
-  /** Required for `"replace"` and `"add"`; ignored for `"remove"`. */
-  readonly value?: unknown;
-  /**
-   * Optional rationale string for audit / write-back commit messages.
-   * The optimizer fills this with the mutation kind + observed delta.
-   */
-  readonly rationale?: string;
-};
-
-const specPatchSchema = z.object({
-  target: z.string().min(1),
-  path: z.array(z.string().min(1)).min(1),
-  op: z.enum(["replace", "add", "remove"]),
-  value: z.unknown().optional(),
-  rationale: z.string().optional(),
-});
-
-export type ApplySpecPatchResult = {
-  /** The mutated YAML text, with comments and key order preserved. */
-  readonly yaml: string;
-  /** The re-parsed Spec after the patch. */
-  readonly spec: Spec;
-};
-
-/**
- * Apply a structured patch to a YAML spec source. Uses the `yaml`
- * package's CST so comments and key order survive the round-trip; the
- * only bytes that change are the ones the patch targets.
- *
- * Validates the resulting document against the Spec schema; throws
- * `SpecPatchError` if the mutation produces invalid spec.
- */
-export function applySpecPatch(yamlText: string, patch: SpecPatch): ApplySpecPatchResult {
-  const parsed = specPatchSchema.safeParse(patch);
-  if (!parsed.success) {
-    throw new SpecPatchError(`patch shape is invalid: ${parsed.error.message}`);
-  }
-  let doc: ReturnType<typeof parseDocument>;
-  try {
-    doc = parseDocument(yamlText);
-  } catch (err) {
-    throw new SpecPatchError("input YAML is not parseable", err);
-  }
-  // Verify the patch matches the spec's target. Cheap pre-check so we
-  // fail with a useful message before the Zod validation later.
-  const docTarget = doc.getIn(["target"]);
-  if (typeof docTarget === "string" && docTarget !== patch.target) {
-    throw new SpecPatchError(
-      `patch target "${patch.target}" does not match spec target "${docTarget}"`,
-    );
-  }
-
-  const path = [...patch.path];
-  switch (patch.op) {
-    case "replace": {
-      if (!doc.hasIn(path)) {
-        throw new SpecPatchError(`cannot replace ${formatPath(path)}: path does not exist`);
-      }
-      doc.setIn(path, patch.value);
-      break;
-    }
-    case "add": {
-      if (doc.hasIn(path)) {
-        throw new SpecPatchError(
-          `cannot add ${formatPath(path)}: path already exists (use "replace")`,
-        );
-      }
-      doc.setIn(path, patch.value);
-      break;
-    }
-    case "remove": {
-      if (!doc.hasIn(path)) {
-        throw new SpecPatchError(`cannot remove ${formatPath(path)}: path does not exist`);
-      }
-      doc.deleteIn(path);
-      break;
-    }
-  }
-
-  const newYaml = doc.toString();
-  let spec: Spec;
-  try {
-    spec = parseSpec(newYaml);
-  } catch (err) {
-    throw new SpecPatchError(`patched YAML failed spec validation: ${(err as Error).message}`, err);
-  }
-  return { yaml: newYaml, spec };
-}
-
-/**
- * Type-check a patch against a parsed Spec WITHOUT applying it. Used
- * by the optimizer to refuse cross-target patches and patches that
- * reference paths outside the optimisation surface.
- *
- * The path-validity check is the "soft" version: it verifies the path
- * is structurally reachable (each segment names a defined field). It
- * does NOT instantiate the patched value — `applySpecPatch` does that
- * via `parseSpec`.
- */
-export function validatePatch(spec: Spec, patch: SpecPatch): void {
-  const parsed = specPatchSchema.safeParse(patch);
-  if (!parsed.success) {
-    throw new SpecPatchError(`patch shape is invalid: ${parsed.error.message}`);
-  }
-  if (patch.target !== spec.target) {
-    throw new SpecPatchError(
-      `patch target "${patch.target}" does not match spec target "${spec.target}"`,
-    );
-  }
-  if (!isOptimizable(spec.target, patch.path)) {
-    throw new SpecPatchError(
-      `path ${formatPath(patch.path)} is not listed in OPTIMIZABLE_PATHS for target "${spec.target}"; add it to packages/spec-patch/src/index.ts if it's intended to be tunable`,
-    );
-  }
-}
-
-function formatPath(path: ReadonlyArray<string>): string {
-  return path.join(".");
-}
-
-/**
- * Per-target whitelist of mutation paths the active optimizer is
- * allowed to touch. Adding a new field here is the explicit signal that
- * it's safe to autotune. Skipping this list means the optimizer can
- * only mutate prompts (the default), preserving the "spec safety floor"
- * that an optimizer can't accidentally rewrite security-critical fields
- * like `permissions.mode` or `model_router` rules.
- */
-export const OPTIMIZABLE_PATHS: Readonly<
-  Record<Spec["target"], ReadonlyArray<ReadonlyArray<string>>>
-> = Object.freeze({
-  cli: Object.freeze([
-    Object.freeze(["agent", "instructions"]),
-    Object.freeze(["failure_taxonomy"]),
-    Object.freeze(["compaction", "threshold"]),
-    // Pillar 2 active context curation — eval-optimizer can flip the
-    // semantic-dedupe + relevance-reorder pass on/off and tune its
-    // similarity threshold, which dominates input-token cost on long runs.
-    Object.freeze(["compaction", "curate"]),
-    Object.freeze(["compaction", "dedupeThreshold"]),
-    Object.freeze(["compaction", "relevanceTopK"]),
-    // Pillar 3 sink-side fabric — egress policy + intent-gate thresholds
-    // are tunable so the eval-optimizer can find the sweet spot between
-    // false-positive denials and false-negative exfil bypasses.
-    Object.freeze(["security", "egressPolicy"]),
-    Object.freeze(["security", "justification"]),
-    // §47 blockchain subsystem (slice 0). Whole-block replacement so the
-    // optimizer can tune `chains[*].finality.count`, `chains[*].rpcPolicy`,
-    // `transaction_policy.maxValueUsd`, and `transaction_policy.simulationRequired`
-    // by patching their parent block.
-    Object.freeze(["chains"]),
-    Object.freeze(["transaction_policy"]),
-  ]),
-  workflow: Object.freeze([
-    Object.freeze(["steps"]),
-    Object.freeze(["failure_taxonomy"]),
-    Object.freeze(["chains"]),
-    Object.freeze(["transaction_policy"]),
-  ]) /* whole-step replacement allowed */,
-  channel: Object.freeze([
-    Object.freeze(["agent", "instructions"]),
-    Object.freeze(["failure_taxonomy"]),
-    Object.freeze(["chains"]),
-    Object.freeze(["transaction_policy"]),
-  ]),
-  graph: Object.freeze([
-    Object.freeze(["nodes"]),
-    Object.freeze(["failure_taxonomy"]),
-    Object.freeze(["chains"]),
-    Object.freeze(["transaction_policy"]),
-  ]),
-  managed: Object.freeze([
-    Object.freeze(["agent", "instructions"]),
-    Object.freeze(["failure_taxonomy"]),
-  ]),
-  pipeline: Object.freeze([
-    Object.freeze(["agent", "instructions"]),
-    Object.freeze(["failure_taxonomy"]),
-    Object.freeze(["indexing", "chunkSize"]),
-    Object.freeze(["indexing", "chunkOverlap"]),
-    Object.freeze(["retrieve", "defaultK"]),
-  ]),
-  crew: Object.freeze([
-    Object.freeze(["roles"]),
-    Object.freeze(["failure_taxonomy"]),
-    Object.freeze(["chains"]),
-    Object.freeze(["transaction_policy"]),
-  ]) /* whole-role replacement */,
-  research: Object.freeze([
-    Object.freeze(["agent", "instructions"]),
-    Object.freeze(["failure_taxonomy"]),
-    Object.freeze(["retrieve", "maxDepth"]),
-    Object.freeze(["chains"]),
-    Object.freeze(["transaction_policy"]),
-  ]),
-  batch: Object.freeze([
-    Object.freeze(["agent", "instructions"]),
-    Object.freeze(["failure_taxonomy"]),
-    Object.freeze(["chains"]),
-    Object.freeze(["transaction_policy"]),
-  ]),
-  voice: Object.freeze([
-    Object.freeze(["agent", "instructions"]),
-    Object.freeze(["failure_taxonomy"]),
-  ]),
-  browser: Object.freeze([
-    Object.freeze(["agent", "instructions"]),
-    Object.freeze(["failure_taxonomy"]),
-  ]),
-  eval: Object.freeze([
-    Object.freeze(["agent", "instructions"]),
-    Object.freeze(["failure_taxonomy"]),
-  ]),
-  // §47 onchain daemon: full cross-cutting blocks are optimizable.
-  onchain: Object.freeze([
-    Object.freeze(["agent", "instructions"]),
-    Object.freeze(["failure_taxonomy"]),
-    Object.freeze(["chains"]),
-    Object.freeze(["triggers"]),
-    Object.freeze(["transaction_policy"]),
-    Object.freeze(["idempotencyWindowMs"]),
-  ]),
-  // §47 onchain-game: instructions, game.objective, and the policy are
-  // the productive knobs; move-timeout-ms is the realtime quality knob.
-  "onchain-game": Object.freeze([
-    Object.freeze(["agent", "instructions"]),
-    Object.freeze(["failure_taxonomy"]),
-    Object.freeze(["game"]),
-    Object.freeze(["transaction_policy"]),
-  ]),
-});
-
-function isOptimizable(target: Spec["target"], path: ReadonlyArray<string>): boolean {
-  const allowed = OPTIMIZABLE_PATHS[target];
-  for (const ok of allowed) {
-    if (ok.length !== path.length) continue;
-    let match = true;
-    for (let i = 0; i < ok.length; i++) {
-      if (ok[i] !== path[i]) {
-        match = false;
-        break;
-      }
-    }
-    if (match) return true;
-  }
-  // Allow patches with a prefix that matches an optimizable path
-  // (e.g. `["nodes", "0", "instructions"]` if `["nodes"]` is whitelisted)
-  // so the optimizer can do fine-grained updates without listing every
-  // sub-path.
-  for (const ok of allowed) {
-    if (path.length < ok.length) continue;
-    let match = true;
-    for (let i = 0; i < ok.length; i++) {
-      if (ok[i] !== path[i]) {
-        match = false;
-        break;
-      }
-    }
-    if (match) return true;
-  }
-  return false;
-}
-
-/**
- * Format a YAML header comment to prepend to a written-back file. The
- * orchestrator's `--write-back` writes this above the original spec so
- * a human reviewer can see when and by what an optimisation pass ran.
- */
-export function formatWriteBackHeader(opts: {
-  readonly runId: string;
-  readonly mutator: string;
-  readonly scoreBefore: number;
-  readonly scoreAfter: number;
-  readonly iterations: number;
-  readonly timestamp?: string;
-}): string {
-  const ts = opts.timestamp ?? new Date().toISOString();
-  const delta = (opts.scoreAfter - opts.scoreBefore).toFixed(3);
-  return [
-    `# crewhaus optimize: runId ${opts.runId}`,
-    `# - mutator: ${opts.mutator}`,
-    `# - iterations: ${opts.iterations}`,
-    `# - score: ${opts.scoreBefore.toFixed(3)} → ${opts.scoreAfter.toFixed(3)} (Δ ${delta})`,
-    `# - generated: ${ts}`,
-    "",
-  ].join("\n");
-}