@verevoir/recipes 0.9.0 → 0.10.0

package/dist/engine.d.ts

@@ -1,4 +1,6 @@
 export * from './retrieval.js';
 export * from './provisioning.js';
 export * from './plan.js';
+export * from './verify.js';
+export * from './run-verify.js';
 //# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAIA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAIA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}

package/dist/engine.js

@@ -5,4 +5,6 @@
 export * from './retrieval.js';
 export * from './provisioning.js';
 export * from './plan.js';
+export * from './verify.js';
+export * from './run-verify.js';
 //# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,gFAAgF;AAChF,oFAAoF;AACpF,kFAAkF;AAClF,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC"}
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,gFAAgF;AAChF,oFAAoF;AACpF,kFAAkF;AAClF,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}

package/dist/run-verify.d.ts

@@ -0,0 +1,46 @@
+import { type Verifier, type VerifyFinding } from './verify.js';
+/** Default cap on produce→verify attempts. A few passes to fix what the gate
+ * found; if it can't, the run is not done rather than shipping unmet work. */
+export declare const DEFAULT_MAX_VERIFY_ATTEMPTS = 3;
+/** What the producer is told for one attempt: the findings from the previous
+ * verify (empty on the first attempt) to fix, and the 1-based attempt number. */
+export interface ProduceAttempt {
+    findings: VerifyFinding[];
+    attempt: number;
+}
+export interface RunWithVerifyInput {
+    capability: string;
+    /** The verifier name the capability declared (`descriptor.verify`). */
+    verify: string;
+    /** Produce the artefact and return the producer's final text. The first call
+     * gets no findings; later calls get the prior verdict's findings to fix. */
+    produce: (attempt: ProduceAttempt) => Promise<string>;
+    /** The resolved check — reads the produced artefact back and verifies it. */
+    verifier: Verifier;
+    /** Cap on attempts. Defaults to DEFAULT_MAX_VERIFY_ATTEMPTS. */
+    maxAttempts?: number;
+}
+export interface RunWithVerifyResult {
+    /** The converged producer output, or the last attempt's if it never did. */
+    result: string;
+    /** How many produce→verify attempts ran (1-based). */
+    attempts: number;
+    /** Whether the verifier ultimately passed. */
+    converged: boolean;
+    /** The final attempt's findings — empty when converged. */
+    findings: VerifyFinding[];
+}
+/**
+ * Run the produce→verify loop. Returns the outcome truthfully (converged or not)
+ * rather than throwing — the host decides whether a non-converged run fails the
+ * work (`enforceConverged`) or is recorded (the cross-model matrix wants the
+ * attempt count, not an exception). Always runs `produce` at least once.
+ */
+export declare function runWithVerify(input: RunWithVerifyInput): Promise<RunWithVerifyResult>;
+/**
+ * Fail-closed gate over a run's outcome: throw when it didn't converge, with the
+ * unmet findings, so a host that must not ship red is a one-liner. Returns the
+ * result unchanged when it converged.
+ */
+export declare function enforceConverged(capability: string, verify: string, outcome: RunWithVerifyResult): RunWithVerifyResult;
+//# sourceMappingURL=run-verify.d.ts.map

package/dist/run-verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-verify.d.ts","sourceRoot":"","sources":["../src/run-verify.ts"],"names":[],"mappings":"AAYA,OAAO,EAA2B,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEzF;8EAC8E;AAC9E,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C;iFACiF;AACjF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf;gFAC4E;IAC5E,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,6EAA6E;IAC7E,QAAQ,EAAE,QAAQ,CAAC;IACnB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,2DAA2D;IAC3D,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAwB3F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,mBAAmB,GAC3B,mBAAmB,CAOrB"}

package/dist/run-verify.js

@@ -0,0 +1,56 @@
+// The verify runner — the shared produce→verify→re-produce loop that enforces a
+// capability's declared postcondition. A capability that declares a `verify` is
+// "done" only when its verifier passes: produce, check, and on a not-clean
+// verdict re-produce with the findings folded in, looping to a cap. The
+// producer's output is an INPUT to the check, never trusted as final.
+//
+// PURE of model + IO: `produce` (the host's enact/tool loop) and `verifier` (the
+// host's resolved check, reading the artefact back through its own adapter) are
+// injected, so the loop is provider-agnostic and unit-testable with no network.
+// It is the binary-gate sibling of the score-based refine loop (Ralph
+// runRefineLoop); a rubric/prose verify that needs scoring routes through that.
+import { isClean, formatFindings } from './verify.js';
+/** Default cap on produce→verify attempts. A few passes to fix what the gate
+ * found; if it can't, the run is not done rather than shipping unmet work. */
+export const DEFAULT_MAX_VERIFY_ATTEMPTS = 3;
+/**
+ * Run the produce→verify loop. Returns the outcome truthfully (converged or not)
+ * rather than throwing — the host decides whether a non-converged run fails the
+ * work (`enforceConverged`) or is recorded (the cross-model matrix wants the
+ * attempt count, not an exception). Always runs `produce` at least once.
+ */
+export async function runWithVerify(input) {
+    // Non-finite (NaN/Infinity from a `Number(unset_env)` or a bad config) falls
+    // back to the default — `??` only catches null/undefined, and a NaN cap would
+    // make the loop run zero attempts, silently skipping the work.
+    const requested = input.maxAttempts;
+    const cap = Number.isFinite(requested) ? requested : DEFAULT_MAX_VERIFY_ATTEMPTS;
+    const max = Math.max(1, Math.floor(cap));
+    let findings = [];
+    let result = '';
+    for (let attempt = 1; attempt <= max; attempt += 1) {
+        result = await input.produce({ findings, attempt });
+        const verdict = await input.verifier({
+            capability: input.capability,
+            verify: input.verify,
+            result,
+        });
+        if (isClean(verdict)) {
+            return { result, attempts: attempt, converged: true, findings: [] };
+        }
+        findings = verdict.findings;
+    }
+    return { result, attempts: max, converged: false, findings };
+}
+/**
+ * Fail-closed gate over a run's outcome: throw when it didn't converge, with the
+ * unmet findings, so a host that must not ship red is a one-liner. Returns the
+ * result unchanged when it converged.
+ */
+export function enforceConverged(capability, verify, outcome) {
+    if (!outcome.converged) {
+        throw new Error(`${capability} failed its verify (${verify}) after ${outcome.attempts} attempt(s):\n${formatFindings(outcome.findings)}`);
+    }
+    return outcome;
+}
+//# sourceMappingURL=run-verify.js.map

package/dist/run-verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-verify.js","sourceRoot":"","sources":["../src/run-verify.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,gFAAgF;AAChF,2EAA2E;AAC3E,wEAAwE;AACxE,sEAAsE;AACtE,EAAE;AACF,iFAAiF;AACjF,gFAAgF;AAChF,gFAAgF;AAChF,sEAAsE;AACtE,gFAAgF;AAEhF,OAAO,EAAE,OAAO,EAAE,cAAc,EAAqC,MAAM,aAAa,CAAC;AAEzF;8EAC8E;AAC9E,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAiC7C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAyB;IAC3D,6EAA6E;IAC7E,8EAA8E;IAC9E,+DAA+D;IAC/D,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,CAAC;IACpC,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAE,SAAoB,CAAC,CAAC,CAAC,2BAA2B,CAAC;IAC7F,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACzC,IAAI,QAAQ,GAAoB,EAAE,CAAC;IACnC,IAAI,MAAM,GAAG,EAAE,CAAC;IAEhB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,GAAG,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QACnD,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC;YACnC,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,MAAM;SACP,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACrB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QACtE,CAAC;QACD,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,UAAkB,EAClB,MAAc,EACd,OAA4B;IAE5B,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,GAAG,UAAU,uBAAuB,MAAM,WAAW,OAAO,CAAC,QAAQ,iBAAiB,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CACzH,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/verify.d.ts

@@ -0,0 +1,44 @@
+/** How a capability's (or practice's) conformance is checked: a mechanical check
+ * (gate), a model scored against a rubric (threshold), or irreducible judgement
+ * (advisory, not a gate). */
+export type VerifyKind = 'deterministic' | 'rubric' | 'prose';
+/** One thing a verifier found wrong, model-actionable so a re-produce can fix
+ * it. `kind` is the verifier's own finding code (e.g. `DTCG`, `VALUE_DRIFT`). */
+export interface VerifyFinding {
+    kind: string;
+    file?: string;
+    where?: string;
+    message: string;
+}
+/** A verifier's verdict. `ok` is the pass/fail (a rubric/prose verifier may pass
+ * or fail with no structured findings); `findings` are the actionable detail a
+ * re-produce fixes. A deterministic verifier keeps them in lock-step (`ok` ⟺ no
+ * findings); use `isClean` rather than reading either field alone. */
+export interface VerifyResult {
+    ok: boolean;
+    findings: VerifyFinding[];
+}
+/** What the runtime hands a verifier. The producer's `result` is grounding for a
+ * rubric/judge; a deterministic verifier ignores it and reads the produced
+ * artefact back itself (off a branch, off disk) — which is why the host binds
+ * its own IO into the closure rather than this carrying a repo handle. */
+export interface VerifyInput {
+    capability: string;
+    /** The verifier name the capability declared (`descriptor.verify`). */
+    verify: string;
+    /** The producer's final text. */
+    result: string;
+}
+/** The check the runtime runs as a hard postcondition — the producer's output is
+ * an INPUT to it, never trusted as final. Async: a real check reads an artefact
+ * back or calls a judge. */
+export type Verifier = (input: VerifyInput) => Promise<VerifyResult>;
+/** True when a run passed its verify — fail-closed across all kinds. A
+ * deterministic verifier signals pass by empty findings; a rubric/prose one
+ * signals it by `ok` and may carry no structured findings — so EITHER a falsy
+ * `ok` or any finding reads as not-clean, and a malformed `{ ok: true,
+ * findings: [...] }` stays not-clean too. */
+export declare function isClean(result: VerifyResult): boolean;
+/** Render findings as model-readable lines for a re-produce directive. */
+export declare function formatFindings(findings: VerifyFinding[]): string;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAMA;;6BAE6B;AAC7B,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE9D;iFACiF;AACjF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;sEAGsE;AACtE,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED;;;0EAG0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;4BAE4B;AAC5B,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAErE;;;;6CAI6C;AAC7C,wBAAgB,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAErD;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,CAMhE"}

package/dist/verify.js

@@ -0,0 +1,20 @@
+// The verify contract — shared vocabulary for a capability's enforced
+// postcondition. A capability declares a `verify` name (index.ts); the runtime
+// resolves it to a Verifier and runs it as a hard gate, looping the producer on
+// its findings until clean. `kind` says how conformance is judged — the same
+// spectrum the refine/eval loop tools use (deterministic / judge / practices).
+/** True when a run passed its verify — fail-closed across all kinds. A
+ * deterministic verifier signals pass by empty findings; a rubric/prose one
+ * signals it by `ok` and may carry no structured findings — so EITHER a falsy
+ * `ok` or any finding reads as not-clean, and a malformed `{ ok: true,
+ * findings: [...] }` stays not-clean too. */
+export function isClean(result) {
+    return result.ok && result.findings.length === 0;
+}
+/** Render findings as model-readable lines for a re-produce directive. */
+export function formatFindings(findings) {
+    return findings
+        .map((f) => `- ${f.kind}${f.file ? ` ${f.file}` : ''}${f.where ? ` ${f.where}` : ''}: ${f.message}`)
+        .join('\n');
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,+EAA+E;AAC/E,gFAAgF;AAChF,6EAA6E;AAC7E,+EAA+E;AA0C/E;;;;6CAI6C;AAC7C,MAAM,UAAU,OAAO,CAAC,MAAoB;IAC1C,OAAO,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC;AACnD,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,QAAyB;IACtD,OAAO,QAAQ;SACZ,GAAG,CACF,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAC/F;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verevoir/recipes",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Recipe-descriptor format + zero-dependency parser: a flat-frontmatter .md describes a parameterised procedure (typed inputs → instructions → result) that a host compiles to a chat-time tool or an MCP prompt.",
   "license": "Apache-2.0",
   "type": "module",