@crewhaus/spec-patch 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -91,6 +91,59 @@ export declare function applySpecPatch(yamlText: string, patch: SpecPatch): Appl
  * via `parseSpec`.
  */
 export declare function validatePatch(spec: Spec, patch: SpecPatch): void;
+/**
+ * Loop contract 0.4 (Batch B, G40) — one edit in an `applySpecEdits` batch.
+ *
+ * Where `SpecPatch` is the optimizer's IMPERATIVE op (`add` vs `replace` vs
+ * `remove`, each with a strict presence pre-check), `SpecEdit` is the
+ * DECLARATIVE surface shared by spec authors (the studio's form fields, the
+ * compiler-worker) and the optimizer: "make `path` carry `value`" (upsert —
+ * creates missing intermediate collections) or, when `value` is `undefined`,
+ * "make `path` absent" (idempotent — deleting an already-absent path is a
+ * no-op, so a cleared form field never needs to track prior presence).
+ *
+ * Paths may address sequence items by non-negative integer index (numeric
+ * strings work too — the CST coerces them for sequences): `["steps", 0,
+ * "instructions"]`. Index `length` appends; anything past that is an error
+ * (never null-padding), and a brand-new sequence can only start at index 0.
+ */
+export type SpecEditPathSegment = string | number;
+export type SpecEdit = {
+    readonly path: ReadonlyArray<SpecEditPathSegment>;
+    /** New value at `path` (upsert). `undefined` — or omitting the key — DELETES the path. */
+    readonly value?: unknown;
+    /** Optional rationale string for audit / write-back commit messages. */
+    readonly rationale?: string;
+};
+export type ApplySpecEditsOptions = {
+    /**
+     * The optimizer surface: every edit path must fall under the spec target's
+     * `OPTIMIZABLE_PATHS` whitelist (exact or prefix match, same rule as
+     * `validatePatch`). Author surfaces leave this off and may edit any field —
+     * the atomic `parseSpec` re-validation is their safety floor.
+     */
+    readonly restrictToOptimizable?: boolean;
+};
+export type ApplySpecEditsResult = {
+    /** The mutated YAML text, with comments and key order preserved. */
+    readonly yaml: string;
+    /** The re-parsed Spec after the whole batch. */
+    readonly spec: Spec;
+    /** Edits that changed the document — idempotent deletes of absent paths don't count. */
+    readonly applied: number;
+};
+/**
+ * Apply a batch of `SpecEdit`s to a YAML spec source ATOMICALLY: all edits
+ * mutate one CST in order, the result is re-validated via `parseSpec` once,
+ * and any failure — a malformed edit, an out-of-bounds sequence index, or a
+ * batch that produces an invalid spec — throws `SpecPatchError` without
+ * yielding a partially-edited text. Comments and key order survive exactly
+ * as in `applySpecPatch` (same `yaml`-package CST underneath).
+ *
+ * A zero-edit batch is a validated no-op: the input text is returned
+ * byte-identical (no CST round-trip reformatting).
+ */
+export declare function applySpecEdits(yamlText: string, edits: ReadonlyArray<SpecEdit>, opts?: ApplySpecEditsOptions): ApplySpecEditsResult;
 /**
  * Per-target whitelist of mutation paths the active optimizer is
  * allowed to touch. Adding a new field here is the explicit signal that

package/dist/index.js

@@ -32,7 +32,7 @@
  */
 import { CrewhausError } from "@crewhaus/errors";
 import { parseSpec } from "@crewhaus/spec";
-import { parse, parseDocument } from "yaml";
+import { isSeq, parse, parseDocument } from "yaml";
 import { z } from "zod";
 import { REDACTED_VALUE, isCredentialKey, maskCredentialTokens } from "./redact";
 // Re-exported so downstream renderers (the CLI changelog, future reporters)
@@ -152,6 +152,135 @@ export function validatePatch(spec, patch) {
 function formatPath(path) {
     return path.join(".");
 }
+const specEditSchema = z.object({
+    path: z.array(z.union([z.string().min(1), z.number().int().nonnegative()])).min(1),
+    value: z.unknown().optional(),
+    rationale: z.string().optional(),
+});
+/**
+ * Apply a batch of `SpecEdit`s to a YAML spec source ATOMICALLY: all edits
+ * mutate one CST in order, the result is re-validated via `parseSpec` once,
+ * and any failure — a malformed edit, an out-of-bounds sequence index, or a
+ * batch that produces an invalid spec — throws `SpecPatchError` without
+ * yielding a partially-edited text. Comments and key order survive exactly
+ * as in `applySpecPatch` (same `yaml`-package CST underneath).
+ *
+ * A zero-edit batch is a validated no-op: the input text is returned
+ * byte-identical (no CST round-trip reformatting).
+ */
+export function applySpecEdits(yamlText, edits, opts = {}) {
+    edits.forEach((edit, i) => {
+        const parsed = specEditSchema.safeParse(edit);
+        if (!parsed.success) {
+            throw new SpecPatchError(`edit #${i} shape is invalid: ${parsed.error.message}`);
+        }
+    });
+    if (edits.length === 0) {
+        let spec;
+        try {
+            spec = parseSpec(yamlText);
+        }
+        catch (err) {
+            throw new SpecPatchError(`input YAML failed spec validation: ${err.message}`, err);
+        }
+        return { yaml: yamlText, spec, applied: 0 };
+    }
+    let doc;
+    try {
+        doc = parseDocument(yamlText);
+    }
+    catch (err) {
+        throw new SpecPatchError("input YAML is not parseable", err);
+    }
+    // `parseDocument` collects syntax errors on `doc.errors` instead of
+    // throwing — without this check they'd only surface as the CST's opaque
+    // "Document with errors cannot be stringified" at toString() time.
+    if (doc.errors.length > 0) {
+        throw new SpecPatchError(`input YAML is not parseable: ${doc.errors[0]?.message ?? "unknown error"}`);
+    }
+    if (opts.restrictToOptimizable === true) {
+        const docTarget = doc.getIn(["target"]);
+        if (typeof docTarget !== "string" || !(docTarget in OPTIMIZABLE_PATHS)) {
+            throw new SpecPatchError(`cannot restrict to optimizable paths: spec target ${JSON.stringify(docTarget)} is not a known target`);
+        }
+        edits.forEach((edit, i) => {
+            if (!isOptimizable(docTarget, edit.path)) {
+                throw new SpecPatchError(`edit #${i}: path ${formatEditPath(edit.path)} is not listed in OPTIMIZABLE_PATHS for target "${docTarget}"; add it to packages/spec-patch/src/index.ts if it's intended to be tunable`);
+            }
+        });
+    }
+    let applied = 0;
+    edits.forEach((edit, i) => {
+        const path = [...edit.path];
+        const label = `edit #${i} (${formatEditPath(path)})`;
+        if (edit.value === undefined) {
+            // Delete-on-undefined. hasIn is false both for an absent leaf and for a
+            // scalar intermediate, so the deleteIn below can never hit the CST's
+            // "Expected YAML collection" throw — absent paths are a clean no-op.
+            if (doc.hasIn(path)) {
+                doc.deleteIn(path);
+                applied += 1;
+            }
+            return;
+        }
+        guardSequenceIndices(doc, path, label);
+        try {
+            doc.setIn(path, edit.value);
+        }
+        catch (err) {
+            throw new SpecPatchError(`${label} failed: ${err.message}`, err);
+        }
+        applied += 1;
+    });
+    const newYaml = doc.toString();
+    let spec;
+    try {
+        spec = parseSpec(newYaml);
+    }
+    catch (err) {
+        throw new SpecPatchError(`edited YAML failed spec validation: ${err.message}`, err);
+    }
+    return { yaml: newYaml, spec, applied };
+}
+/**
+ * Pre-flight for `setIn` along a path that may address sequences: the CST
+ * happily null-pads a sequence up to any index (`steps[5]` on a 2-step list
+ * yields three `null` steps), which is never what an author or optimizer
+ * meant. Reject indices past `length` (index === `length` appends) and
+ * refuse to CREATE a sequence anywhere but at index 0. Map keys and the
+ * CST's own errors (negative / non-integer index, scalar intermediates)
+ * pass through untouched — the caller wraps those with the edit label.
+ */
+function guardSequenceIndices(doc, path, label) {
+    for (let i = 0; i < path.length; i++) {
+        const seg = path[i];
+        const parent = i === 0 ? doc.contents : doc.getIn(path.slice(0, i), true);
+        const asIndex = typeof seg === "number" ? seg : /^\d+$/.test(seg) ? Number.parseInt(seg, 10) : undefined;
+        if (isSeq(parent)) {
+            if (asIndex !== undefined && asIndex > parent.items.length) {
+                throw new SpecPatchError(`${label}: index ${asIndex} is out of bounds for the sequence at ${i === 0 ? "(root)" : formatEditPath(path.slice(0, i))} (length ${parent.items.length}; index ${parent.items.length} appends)`);
+            }
+        }
+        else if (parent === undefined && typeof seg === "number" && seg !== 0) {
+            throw new SpecPatchError(`${label}: cannot create a new sequence at ${i === 0 ? "(root)" : formatEditPath(path.slice(0, i))} starting at index ${seg} — a new sequence starts at index 0`);
+        }
+    }
+}
+/** Render an edit path for messages: string keys dot-joined, integer
+ *  sequence indices as `[i]` — `["steps", 0, "instructions"]` →
+ *  `steps[0].instructions`. */
+function formatEditPath(path) {
+    let out = "";
+    for (const seg of path) {
+        if (typeof seg === "number") {
+            out += `[${seg}]`;
+        }
+        else {
+            out += out === "" ? seg : `.${seg}`;
+        }
+    }
+    return out;
+}
 /**
  * Per-target whitelist of mutation paths the active optimizer is
  * allowed to touch. Adding a new field here is the explicit signal that
@@ -167,7 +296,15 @@ export const OPTIMIZABLE_PATHS = Object.freeze({
         // per-turn output-token cap when max_tokens truncations recur; safe to
         // autotune (a bigger cap can only trade cost for completeness).
         Object.freeze(["agent", "max_tokens"]),
+        // Loop contract 0.4 (Batch A) — the explicit thinking-token budget is a
+        // pure quality/cost dial (>= 1024 enforced by the spec); the optimizer
+        // may raise/lower it but never flips the thinking FORM (effort presets
+        // stay human-owned via the exactly-one-form superRefine).
+        Object.freeze(["agent", "thinking", "budget_tokens"]),
         Object.freeze(["failure_taxonomy"]),
+        // Loop contract 0.4 (Batch A) — real as of the `compaction.threshold`
+        // spec field (0.5–0.99): when to trigger autocompaction is a classic
+        // token-cost vs context-completeness dial.
         Object.freeze(["compaction", "threshold"]),
         // Pillar 2 active context curation — eval-optimizer can flip the
         // semantic-dedupe + relevance-reorder pass on/off and tune its
@@ -175,10 +312,16 @@ export const OPTIMIZABLE_PATHS = Object.freeze({
         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"]),
+        // Loop contract 0.4 (Batch A) — tool-iteration ceiling: quality (task
+        // completion) vs runaway-cost dial. NOTE ["security","egressPolicy"]
+        // was REMOVED here: the spec never grew that key (strict schemas
+        // reject it), and the OPTIMIZABLE_PATHS guard test requires every
+        // listed path to round-trip through parseSpec. Re-add it WITH the spec
+        // field when the egress-fabric FRs ship it.
+        Object.freeze(["limits", "max_tool_iterations"]),
+        // Pillar 3 intent gate — tunable so the eval-optimizer can find the
+        // sweet spot between false-positive denials and false-negative exfil
+        // bypasses.
         Object.freeze(["security", "justification"]),
         // §47 blockchain subsystem (slice 0). Whole-block replacement so the
         // optimizer can tune `chains[*].finality.count`, `chains[*].rpcPolicy`,
@@ -212,26 +355,63 @@ export const OPTIMIZABLE_PATHS = Object.freeze({
         //                                the volatile tail block (token cost vs
         //                                plan/ledger completeness)
         // Deliberately EXCLUDED — the optimizer tunes quality, never semantics:
-        // thredz.* (credentials), memory.backend (store flip), memory.dream.every
-        // + .mode (side-effecting schedule / model-spend switch), continuity
+        // thredz.* (credentials; thredz.messaging = a destructive send-tool
+        // switch), memory.backend (store flip), memory.dream.every + .mode
+        // (side-effecting schedule / model-spend switch), continuity
         // .proof/.scope/.enabled (behavioral switches), compaction
         // .preserve_user_messages (safety), learning.sources (allowlist =
-        // security).
+        // security). Batch G adds more of the same category: expose.* (G30 — the
+        // deployment/exposure surface, not a quality knob), plugins (G32 — a
+        // capability allowlist = supply-chain security, human-owned like
+        // learning.sources / the model roster), and sub_agents.*.federation (G31
+        // — cross-deployment wiring / trust boundary). None are optimizer-reachable.
         Object.freeze(["memory", "recallK"]),
         Object.freeze(["memory", "autoCaptureThreshold"]),
         Object.freeze(["memory", "ttl"]),
         Object.freeze(["memory", "wiki", "recallK"]),
         Object.freeze(["memory", "dream", "budget_usd"]),
         Object.freeze(["continuity", "focusMaxChars"]),
+        // Loop contract 0.4 (Batch B, G40) — the in-loop evaluation dials. The
+        // pass bar (llm_judge graders only — the spec rejects threshold on
+        // deterministic graders, so a mis-aimed patch fails the re-parse) and
+        // the retry cap are classic quality-vs-cost knobs. Deliberately NOT
+        // ["evaluation"] wholesale and NOT ["evaluation","grader"]: the grader
+        // (criteria/type) and on_fail behaviour are human-owned semantics —
+        // the optimizer tunes how strict the gate is, never what it judges.
+        Object.freeze(["evaluation", "threshold"]),
+        Object.freeze(["evaluation", "max_retries"]),
+        // Loop contract 0.4 (Batch E) — the agent-shape RAG (`knowledge:`) dials
+        // + the per-turn recall cadence. All scalars that survive lower() 1:1
+        // with their bounds owned by the spec schema, so an out-of-bounds patch
+        // fails applySpecPatch's re-parse. `default_k` (hits/turn) and the chunker
+        // window are classic recall-quality vs token-cost dials; `refreshEvery`
+        // trades recall freshness against per-turn recall cost. Deliberately NOT
+        // ["knowledge"] wholesale and NOT ["knowledge","sources"]: the corpus
+        // (an allowlist of what the agent may read) is human-owned, mirroring the
+        // learning.sources / model-roster exclusions.
+        Object.freeze(["knowledge", "default_k"]),
+        Object.freeze(["knowledge", "chunk", "size"]),
+        Object.freeze(["knowledge", "chunk", "overlap"]),
+        Object.freeze(["memory", "refreshEvery"]),
     ]),
     workflow: Object.freeze([
+        // Whole-step replacement — this ALSO reaches item 9's (G37) per-step
+        // model routing (model_pool policy/routing/learning, tiers, fallbacks):
+        // no narrower entry is possible (the roster/step index is positional) and
+        // whole-step replacement already spans model/instructions, so the policy
+        // knobs ride here rather than as standalone paths.
         Object.freeze(["steps"]),
         Object.freeze(["failure_taxonomy"]),
         Object.freeze(["chains"]),
         Object.freeze(["transaction_policy"]),
+        // Loop contract 0.4 (Batch A) — see the cli entry.
+        Object.freeze(["limits", "max_tool_iterations"]),
     ]) /* whole-step replacement allowed */,
     channel: Object.freeze([
         Object.freeze(["agent", "instructions"]),
+        // Loop contract 0.4 (Batch A) — see the cli entries.
+        Object.freeze(["agent", "thinking", "budget_tokens"]),
+        Object.freeze(["limits", "max_tool_iterations"]),
         Object.freeze(["failure_taxonomy"]),
         Object.freeze(["chains"]),
         Object.freeze(["transaction_policy"]),
@@ -246,15 +426,28 @@ export const OPTIMIZABLE_PATHS = Object.freeze({
         Object.freeze(["memory", "wiki", "recallK"]),
         Object.freeze(["memory", "dream", "budget_usd"]),
         Object.freeze(["continuity", "focusMaxChars"]),
+        // Loop contract 0.4 (Batch B, G40) — evaluation dials; see the cli entry.
+        Object.freeze(["evaluation", "threshold"]),
+        Object.freeze(["evaluation", "max_retries"]),
+        // Loop contract 0.4 (Batch E) — knowledge/recall dials; see the cli entry.
+        Object.freeze(["knowledge", "default_k"]),
+        Object.freeze(["knowledge", "chunk", "size"]),
+        Object.freeze(["knowledge", "chunk", "overlap"]),
+        Object.freeze(["memory", "refreshEvery"]),
     ]),
     graph: Object.freeze([
         Object.freeze(["nodes"]),
         Object.freeze(["failure_taxonomy"]),
         Object.freeze(["chains"]),
         Object.freeze(["transaction_policy"]),
+        // Loop contract 0.4 (Batch A) — see the cli entry.
+        Object.freeze(["limits", "max_tool_iterations"]),
     ]),
     managed: Object.freeze([
         Object.freeze(["agent", "instructions"]),
+        // Loop contract 0.4 (Batch A) — see the cli entries.
+        Object.freeze(["agent", "thinking", "budget_tokens"]),
+        Object.freeze(["limits", "max_tool_iterations"]),
         Object.freeze(["failure_taxonomy"]),
         // Adaptive model routing — pool policy knobs only (see the cli entry).
         Object.freeze(["agent", "model_pool", "policy"]),
@@ -267,6 +460,14 @@ export const OPTIMIZABLE_PATHS = Object.freeze({
         Object.freeze(["memory", "wiki", "recallK"]),
         Object.freeze(["memory", "dream", "budget_usd"]),
         Object.freeze(["continuity", "focusMaxChars"]),
+        // Loop contract 0.4 (Batch B, G40) — evaluation dials; see the cli entry.
+        Object.freeze(["evaluation", "threshold"]),
+        Object.freeze(["evaluation", "max_retries"]),
+        // Loop contract 0.4 (Batch E) — knowledge/recall dials; see the cli entry.
+        Object.freeze(["knowledge", "default_k"]),
+        Object.freeze(["knowledge", "chunk", "size"]),
+        Object.freeze(["knowledge", "chunk", "overlap"]),
+        Object.freeze(["memory", "refreshEvery"]),
     ]),
     pipeline: Object.freeze([
         Object.freeze(["agent", "instructions"]),
@@ -276,10 +477,17 @@ export const OPTIMIZABLE_PATHS = Object.freeze({
         Object.freeze(["retrieve", "defaultK"]),
     ]),
     crew: Object.freeze([
+        // Whole-role replacement — this ALSO reaches item 9's (G37) per-role
+        // model routing (model_pool policy/routing/learning, tiers, fallbacks):
+        // the role name is a dynamic map key, so no static narrower path exists,
+        // and whole-role replacement already spans model/instructions, so the
+        // policy knobs ride here rather than as standalone paths.
         Object.freeze(["roles"]),
         Object.freeze(["failure_taxonomy"]),
         Object.freeze(["chains"]),
         Object.freeze(["transaction_policy"]),
+        // Loop contract 0.4 (Batch A) — see the cli entry.
+        Object.freeze(["limits", "max_tool_iterations"]),
         // 0.3.0 memory/continuity quality knobs — types/bounds at the cli entry.
         Object.freeze(["memory", "recallK"]),
         Object.freeze(["memory", "autoCaptureThreshold"]),
@@ -287,13 +495,20 @@ export const OPTIMIZABLE_PATHS = Object.freeze({
         Object.freeze(["memory", "wiki", "recallK"]),
         Object.freeze(["memory", "dream", "budget_usd"]),
         Object.freeze(["continuity", "focusMaxChars"]),
+        // Loop contract 0.4 (Batch E) — per-turn recall cadence; see the cli entry.
+        Object.freeze(["memory", "refreshEvery"]),
     ]) /* whole-role replacement */,
     research: Object.freeze([
         Object.freeze(["agent", "instructions"]),
         Object.freeze(["failure_taxonomy"]),
-        Object.freeze(["retrieve", "maxDepth"]),
+        // NOTE ["retrieve","maxDepth"] was REMOVED here (Batch A): the research
+        // retrieve block never grew a maxDepth field (strict schema rejects
+        // it), and the OPTIMIZABLE_PATHS guard test requires every listed path
+        // to round-trip through parseSpec. Re-add it WITH the spec field.
         Object.freeze(["chains"]),
         Object.freeze(["transaction_policy"]),
+        // Loop contract 0.4 (Batch A) — see the cli entry.
+        Object.freeze(["limits", "max_tool_iterations"]),
         // 0.3.0 memory/continuity quality knobs — types/bounds at the cli entry.
         Object.freeze(["memory", "recallK"]),
         Object.freeze(["memory", "autoCaptureThreshold"]),
@@ -301,12 +516,16 @@ export const OPTIMIZABLE_PATHS = Object.freeze({
         Object.freeze(["memory", "wiki", "recallK"]),
         Object.freeze(["memory", "dream", "budget_usd"]),
         Object.freeze(["continuity", "focusMaxChars"]),
+        // Loop contract 0.4 (Batch E) — per-turn recall cadence; see the cli entry.
+        Object.freeze(["memory", "refreshEvery"]),
     ]),
     batch: Object.freeze([
         Object.freeze(["agent", "instructions"]),
         Object.freeze(["failure_taxonomy"]),
         Object.freeze(["chains"]),
         Object.freeze(["transaction_policy"]),
+        // Loop contract 0.4 (Batch A) — see the cli entry.
+        Object.freeze(["limits", "max_tool_iterations"]),
     ]),
     voice: Object.freeze([
         Object.freeze(["agent", "instructions"]),
@@ -315,6 +534,8 @@ export const OPTIMIZABLE_PATHS = Object.freeze({
     browser: Object.freeze([
         Object.freeze(["agent", "instructions"]),
         Object.freeze(["failure_taxonomy"]),
+        // Loop contract 0.4 (Batch A) — see the cli entry.
+        Object.freeze(["limits", "max_tool_iterations"]),
     ]),
     eval: Object.freeze([
         Object.freeze(["agent", "instructions"]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/spec-patch",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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": "dist/index.js",
@@ -15,8 +15,8 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.3.1",
-    "@crewhaus/spec": "0.3.1",
+    "@crewhaus/errors": "0.4.0",
+    "@crewhaus/spec": "0.4.0",
     "yaml": "^2.6.0",
     "zod": "^3.23.8"
   },