modelrig 0.8.1 → 0.10.0

package/dist/prompts/slot-resolver.d.ts

@@ -0,0 +1,91 @@
+/**
+ * PSR-2b — the client-fill engine (spec §4 "two-layer resolution", ADJ-2;
+ * authoring-guide §5–§6). Resolves a served {@link Manifest} into an assembled
+ * prompt string, ENTIRELY in the customer's process.
+ *
+ * Per call the SDK walks the manifest's slots IN ORDER (order = send order, D6)
+ * and fills each one:
+ *   • `static`            → authored text (inline `text`, or `from: system|template`)
+ *   • `dynamic·tool`      → the registered {@link ToolFn}, run in-process with the
+ *                           customer's keys (spec §4)
+ *   • `dynamic·cache`     → the declared cache handle, read by the caller's reader
+ *   • `dynamic·upstream`  → the prior step's APPROVED output (from the caller)
+ *   • `dynamic·variable`  → the call's variable whitelist
+ * then assembles the resolved parts in order. The assembled text is a plain
+ * string the caller dispatches through the existing `rig.run`/`runRaw` seam.
+ *
+ * FAIL CLOSED, NEVER SILENT (spec §4, HARD requirement). A `dynamic·tool` slot
+ * whose tool is not registered throws a teaching {@link SlotResolutionError} that
+ * NAMES the missing tool and what IS bound — never an empty slot, never a silent
+ * skip. The same discipline covers every dynamic kind: a slot that cannot be
+ * filled from what the caller provided fails closed, so a half-assembled prompt
+ * is never dispatched.
+ *
+ * PRIVACY: this module has ZERO network/telemetry imports. Its inputs (tool fns,
+ * cache reader, upstream outputs, variables) and its output (the assembled text)
+ * are all in-process values. Nothing tool-derived is sent anywhere — assembly is
+ * a local computation. That is the "tool keys + dynamic data never leave the
+ * process" guarantee, structural rather than promised.
+ */
+import type { Manifest } from "./manifest";
+import type { ToolRegistry } from "./tools-register";
+/** Reads a `dynamic·cache` slot's declared handle into text, in-process. Async
+ * (a cache is usually an out-of-band read). The handle is the slot's
+ * `source.ref`; the reader is the customer's — ModelRig never reads it. */
+export type CacheReader = (handle: string) => string | Promise<string>;
+/**
+ * Everything the resolver needs to fill slots — supplied by the caller, all
+ * in-process. Only the kinds a given manifest uses need be present; a slot of a
+ * kind the caller did not provide for FAILS CLOSED (never a silent empty slot).
+ */
+export interface SlotResolveContext {
+    /** The authored template text a `from: template` static slot pulls (the served
+     * `ServedPrompt.template`). */
+    readonly template: string;
+    /** The authored system text a `from: system` static slot pulls, when the
+     * manifest declares one. */
+    readonly system?: string;
+    /** The tool bindings (`rig.tools`) a `dynamic·tool` slot resolves against. */
+    readonly tools: ToolRegistry;
+    /** The variable whitelist — the customer's own call inputs. A
+     * `dynamic·variable` slot reads `variables[ref]`; also passed to each tool as
+     * its {@link ToolResolveContext.input}. */
+    readonly variables?: Readonly<Record<string, unknown>>;
+    /** Reader for `dynamic·cache` slots. Absent ⇒ a cache slot fails closed. */
+    readonly cache?: CacheReader;
+    /** Prior steps' APPROVED outputs, keyed by step key — a `dynamic·upstream`
+     * slot reads `upstream[ref]`. Absent/missing ref ⇒ fails closed. */
+    readonly upstream?: Readonly<Record<string, string>>;
+}
+/** One resolved slot: its id and the text it contributed, in send order. */
+export interface ResolvedSlot {
+    readonly id: string;
+    readonly text: string;
+}
+/** The assembled prompt plus the per-slot parts (send order preserved). `text`
+ * is `parts` joined with a blank line — the string the caller dispatches. */
+export interface AssembledPrompt {
+    readonly text: string;
+    readonly parts: readonly ResolvedSlot[];
+}
+/**
+ * A slot that could not be filled — the fail-closed signal (spec §4). Carries
+ * the slot id and a teaching message; the tool-unbound case names the missing
+ * tool and the bound names, so the fix is obvious at the call site.
+ */
+export declare class SlotResolutionError extends Error {
+    readonly slotId: string;
+    constructor(slotId: string, message: string);
+}
+/**
+ * Resolve every slot of a served manifest IN ORDER and assemble the prompt
+ * (spec §4). Slots resolve sequentially so `upstream` ordering and any
+ * side-effecting tool run in declared send order. Throws
+ * {@link SlotResolutionError} on the FIRST slot that cannot be filled — the
+ * prompt is never dispatched half-assembled (fail closed).
+ *
+ * Pure over its inputs apart from the tool/cache functions the caller supplies,
+ * which run in-process. The returned {@link AssembledPrompt} is a local value.
+ */
+export declare function assemblePrompt(manifest: Manifest, ctx: SlotResolveContext): Promise<AssembledPrompt>;
+//# sourceMappingURL=slot-resolver.d.ts.map

package/dist/prompts/slot-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot-resolver.d.ts","sourceRoot":"","sources":["../../src/prompts/slot-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAQ,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;2EAE2E;AAC3E,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAEvE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;mCAC+B;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;gCAC4B;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B;;+CAE2C;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B;wEACoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;6EAC6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;CACzC;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK5C;AAiGD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,kBAAkB,GACtB,OAAO,CAAC,eAAe,CAAC,CAO1B"}

package/dist/prompts/slot-resolver.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * PSR-2b — the client-fill engine (spec §4 "two-layer resolution", ADJ-2;
+ * authoring-guide §5–§6). Resolves a served {@link Manifest} into an assembled
+ * prompt string, ENTIRELY in the customer's process.
+ *
+ * Per call the SDK walks the manifest's slots IN ORDER (order = send order, D6)
+ * and fills each one:
+ *   • `static`            → authored text (inline `text`, or `from: system|template`)
+ *   • `dynamic·tool`      → the registered {@link ToolFn}, run in-process with the
+ *                           customer's keys (spec §4)
+ *   • `dynamic·cache`     → the declared cache handle, read by the caller's reader
+ *   • `dynamic·upstream`  → the prior step's APPROVED output (from the caller)
+ *   • `dynamic·variable`  → the call's variable whitelist
+ * then assembles the resolved parts in order. The assembled text is a plain
+ * string the caller dispatches through the existing `rig.run`/`runRaw` seam.
+ *
+ * FAIL CLOSED, NEVER SILENT (spec §4, HARD requirement). A `dynamic·tool` slot
+ * whose tool is not registered throws a teaching {@link SlotResolutionError} that
+ * NAMES the missing tool and what IS bound — never an empty slot, never a silent
+ * skip. The same discipline covers every dynamic kind: a slot that cannot be
+ * filled from what the caller provided fails closed, so a half-assembled prompt
+ * is never dispatched.
+ *
+ * PRIVACY: this module has ZERO network/telemetry imports. Its inputs (tool fns,
+ * cache reader, upstream outputs, variables) and its output (the assembled text)
+ * are all in-process values. Nothing tool-derived is sent anywhere — assembly is
+ * a local computation. That is the "tool keys + dynamic data never leave the
+ * process" guarantee, structural rather than promised.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SlotResolutionError = void 0;
+exports.assemblePrompt = assemblePrompt;
+/**
+ * A slot that could not be filled — the fail-closed signal (spec §4). Carries
+ * the slot id and a teaching message; the tool-unbound case names the missing
+ * tool and the bound names, so the fix is obvious at the call site.
+ */
+class SlotResolutionError extends Error {
+    constructor(slotId, message) {
+        super(message);
+        this.name = "SlotResolutionError";
+        this.slotId = slotId;
+    }
+}
+exports.SlotResolutionError = SlotResolutionError;
+/** The separator between assembled slot parts — a blank line, so adjacent blocks
+ * stay legible and a cache `prefix` slot keeps a stable boundary. */
+const PART_SEPARATOR = "\n\n";
+/** Resolve ONE slot to its text, or throw {@link SlotResolutionError} (fail
+ * closed). Every branch either returns a concrete string or throws — a slot
+ * never resolves to `undefined`/empty by omission. */
+async function resolveSlot(slot, ctx) {
+    if (slot.kind === "static") {
+        if (slot.text !== undefined)
+            return slot.text;
+        if (slot.from === "template")
+            return ctx.template;
+        if (slot.from === "system") {
+            if (ctx.system === undefined) {
+                throw new SlotResolutionError(slot.id, `static slot "${slot.id}" references \`from: system\`, but no authored ` +
+                    "`system` text was provided to the resolver");
+            }
+            return ctx.system;
+        }
+        // A validated manifest guarantees text XOR from; this is unreachable for a
+        // validated slot, but fail closed rather than emit an empty slot.
+        throw new SlotResolutionError(slot.id, `static slot "${slot.id}" has neither inline \`text\` nor a \`from\` reference`);
+    }
+    // dynamic — a validated manifest guarantees a well-formed `source`.
+    const source = slot.source;
+    if (source === undefined) {
+        throw new SlotResolutionError(slot.id, `dynamic slot "${slot.id}" is missing its \`source\``);
+    }
+    const ref = source.ref;
+    switch (source.kind) {
+        case "tool": {
+            const fn = ctx.tools.get(ref);
+            if (fn === undefined) {
+                const bound = ctx.tools.names();
+                const boundList = bound.length > 0 ? `bound tools: ${bound.join(", ")}` : "no tools are bound";
+                throw new SlotResolutionError(slot.id, `slot "${slot.id}" needs tool "${ref}", but it is not bound — call ` +
+                    `rig.tools.register("${ref}", fn) before this route runs (${boundList}). ` +
+                    "The prompt was NOT sent with an empty slot (spec §4, fail closed).");
+            }
+            return fn({ ref, input: ctx.variables ?? {} });
+        }
+        case "cache": {
+            if (ctx.cache === undefined) {
+                throw new SlotResolutionError(slot.id, `slot "${slot.id}" needs cache handle "${ref}", but no cache reader was ` +
+                    "provided to the resolver");
+            }
+            return ctx.cache(ref);
+        }
+        case "upstream": {
+            const value = ctx.upstream?.[ref];
+            if (value === undefined) {
+                throw new SlotResolutionError(slot.id, `slot "${slot.id}" needs the approved output of upstream step "${ref}", ` +
+                    "but it was not provided to the resolver");
+            }
+            return value;
+        }
+        case "variable": {
+            const value = ctx.variables?.[ref];
+            if (value === undefined) {
+                throw new SlotResolutionError(slot.id, `slot "${slot.id}" needs variable "${ref}", but it is not in the call's ` +
+                    "variable whitelist");
+            }
+            return typeof value === "string" ? value : JSON.stringify(value);
+        }
+        default: {
+            // Exhaustive over DynamicSourceKind; a future kind fails closed here.
+            const exhaustive = source.kind;
+            throw new SlotResolutionError(slot.id, `slot "${slot.id}" has an unknown dynamic source kind ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/**
+ * Resolve every slot of a served manifest IN ORDER and assemble the prompt
+ * (spec §4). Slots resolve sequentially so `upstream` ordering and any
+ * side-effecting tool run in declared send order. Throws
+ * {@link SlotResolutionError} on the FIRST slot that cannot be filled — the
+ * prompt is never dispatched half-assembled (fail closed).
+ *
+ * Pure over its inputs apart from the tool/cache functions the caller supplies,
+ * which run in-process. The returned {@link AssembledPrompt} is a local value.
+ */
+async function assemblePrompt(manifest, ctx) {
+    const parts = [];
+    for (const slot of manifest.slots) {
+        const text = await resolveSlot(slot, ctx);
+        parts.push({ id: slot.id, text });
+    }
+    return { text: parts.map((p) => p.text).join(PART_SEPARATOR), parts };
+}

package/dist/prompts/tools-register.d.ts

@@ -0,0 +1,60 @@
+/**
+ * PSR-2b — the client-side tool-binding registry (spec §4 ADJ-2, authoring-guide
+ * §5). The client-fill half of the prompt system-of-record.
+ *
+ * A `dynamic·tool` manifest slot NAMES a tool (`source.ref`, e.g.
+ * `"search_tickets"`); it carries no code and no data (structure-only, D6). To
+ * fill that slot at call time the SDK needs a **client-side binding** from that
+ * name to a function that runs IN THE CUSTOMER'S PROCESS, with the customer's
+ * keys. `rig.tools.register(name, fn)` is that binding.
+ *
+ * The privacy guarantee lives here: a bound tool `fn` closes over the customer's
+ * credentials and does its work locally; ModelRig only ever knows the tool's
+ * NAME (already in the manifest). Nothing this registry holds — not a fn, not a
+ * key it closes over, not a value it returns — is ever serialized or sent
+ * anywhere. This module has ZERO network/telemetry imports, by design, so
+ * "tool keys never leave the process" is a structural property, not a promise.
+ *
+ * Pure + dependency-free.
+ */
+/**
+ * The context a bound tool receives when the SDK resolves its slot. Carries the
+ * tool NAME being filled and the call's variable whitelist (the same values a
+ * `dynamic·variable` slot draws from) so a tool can shape its work from the
+ * call's inputs — never anything ModelRig-side. Read-only: a tool observes, it
+ * does not mutate the call.
+ */
+export interface ToolResolveContext {
+    /** The tool name being resolved (the slot's `source.ref`). */
+    readonly ref: string;
+    /** The call's variable whitelist — the customer's own inputs, in-process. */
+    readonly input: Readonly<Record<string, unknown>>;
+}
+/**
+ * A bound tool: runs in-process with the customer's keys and returns the text
+ * to place in its slot. May be async (a tool usually calls out to the customer's
+ * own upstream). Whatever it returns stays local — it becomes the slot's filled
+ * text and is assembled into the prompt on the customer's machine.
+ */
+export type ToolFn = (ctx: ToolResolveContext) => string | Promise<string>;
+/**
+ * The registry backing `rig.tools`. `register` binds a name → fn (last write
+ * wins, so a re-register is a rebind, never a silent duplicate); `get`/`has`
+ * look a binding up by name; `names` lists the bound names (for a teaching
+ * error). Never throws on read — the caller decides what a missing binding
+ * means (the slot resolver FAILS CLOSED with a teaching error, spec §4).
+ */
+export interface ToolRegistry {
+    /** Bind `name` to `fn`. Rejects an empty name or a non-function with a
+     * teaching error — a misbinding is a bug at the developer's machine, surfaced
+     * at register time, never a mystery at call time. */
+    register(name: string, fn: ToolFn): void;
+    get(name: string): ToolFn | undefined;
+    has(name: string): boolean;
+    /** The bound names, sorted — used to name what IS available when a slot
+     * references a tool that is not. */
+    names(): readonly string[];
+}
+/** Build an empty {@link ToolRegistry}. One per rig; `rig.tools` exposes it. */
+export declare function createToolRegistry(): ToolRegistry;
+//# sourceMappingURL=tools-register.d.ts.map

package/dist/prompts/tools-register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-register.d.ts","sourceRoot":"","sources":["../../src/prompts/tools-register.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD;AAED;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,kBAAkB,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;;yDAEqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACtC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B;wCACoC;IACpC,KAAK,IAAI,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,IAAI,YAAY,CA4BjD"}

package/dist/prompts/tools-register.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * PSR-2b — the client-side tool-binding registry (spec §4 ADJ-2, authoring-guide
+ * §5). The client-fill half of the prompt system-of-record.
+ *
+ * A `dynamic·tool` manifest slot NAMES a tool (`source.ref`, e.g.
+ * `"search_tickets"`); it carries no code and no data (structure-only, D6). To
+ * fill that slot at call time the SDK needs a **client-side binding** from that
+ * name to a function that runs IN THE CUSTOMER'S PROCESS, with the customer's
+ * keys. `rig.tools.register(name, fn)` is that binding.
+ *
+ * The privacy guarantee lives here: a bound tool `fn` closes over the customer's
+ * credentials and does its work locally; ModelRig only ever knows the tool's
+ * NAME (already in the manifest). Nothing this registry holds — not a fn, not a
+ * key it closes over, not a value it returns — is ever serialized or sent
+ * anywhere. This module has ZERO network/telemetry imports, by design, so
+ * "tool keys never leave the process" is a structural property, not a promise.
+ *
+ * Pure + dependency-free.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolRegistry = createToolRegistry;
+/** Build an empty {@link ToolRegistry}. One per rig; `rig.tools` exposes it. */
+function createToolRegistry() {
+    const bindings = new Map();
+    return {
+        register(name, fn) {
+            if (typeof name !== "string" || name.length === 0) {
+                throw new Error("rig.tools.register: the tool name must be a non-empty string (it is the " +
+                    "name a `dynamic·tool` manifest slot references)");
+            }
+            if (typeof fn !== "function") {
+                throw new Error(`rig.tools.register: the binding for tool "${name}" must be a function ` +
+                    "(it runs in-process with your keys to fill the slot)");
+            }
+            bindings.set(name, fn);
+        },
+        get(name) {
+            return bindings.get(name);
+        },
+        has(name) {
+            return bindings.has(name);
+        },
+        names() {
+            return [...bindings.keys()].sort();
+        },
+    };
+}

package/dist/prompts/version-hash.d.ts

@@ -0,0 +1,29 @@
+/**
+ * PSR-2 — the content-hash id for a prompt version (`template_sha`).
+ *
+ * A prompt version is identified by the sha256 of its `template` + `manifest`
+ * (spec §2, the Humanloop content-hash pattern: identical content ⇒ no
+ * duplicate row). This is the ONE definition of that hash, used by:
+ *   • the ingest + create-version writer (dedupe: an identical re-ingest resolves
+ *     to the existing row rather than appending a byte-identical version), and
+ *   • the served-projection check (does routes.bundle carry THIS version? — the
+ *     "served this call" marker compares template_sha, PSR-2b).
+ *
+ * The manifest is CANONICALIZED first (object keys sorted recursively, array
+ * order preserved) so a semantically-identical manifest always hashes the same
+ * regardless of key order in the source artifact — the same discipline
+ * `resolved-bundle.ts` uses for `bundle_sha`. Callers MUST normalize the manifest
+ * ({@link normalizeManifest}) before hashing so incidental unknown keys never
+ * split the dedupe. Pure + dependency-free (node:crypto only).
+ */
+import type { Manifest } from "./manifest";
+/**
+ * The content-hash id of a prompt version — `sha256:<hex>`, self-describing so a
+ * future algorithm change is visible in the stored value rather than silent
+ * (parity with `hashResolvedBundle`). The template is hashed verbatim; the
+ * manifest is canonicalized. The two are joined with a NUL separator that cannot
+ * appear in the template, so no `(template, manifest)` pair can collide with a
+ * different pair by boundary ambiguity.
+ */
+export declare function promptTemplateSha(template: string, manifest: Manifest): string;
+//# sourceMappingURL=version-hash.d.ts.map

package/dist/prompts/version-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-hash.d.ts","sourceRoot":"","sources":["../../src/prompts/version-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAkB3C;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAO9E"}

package/dist/prompts/version-hash.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * PSR-2 — the content-hash id for a prompt version (`template_sha`).
+ *
+ * A prompt version is identified by the sha256 of its `template` + `manifest`
+ * (spec §2, the Humanloop content-hash pattern: identical content ⇒ no
+ * duplicate row). This is the ONE definition of that hash, used by:
+ *   • the ingest + create-version writer (dedupe: an identical re-ingest resolves
+ *     to the existing row rather than appending a byte-identical version), and
+ *   • the served-projection check (does routes.bundle carry THIS version? — the
+ *     "served this call" marker compares template_sha, PSR-2b).
+ *
+ * The manifest is CANONICALIZED first (object keys sorted recursively, array
+ * order preserved) so a semantically-identical manifest always hashes the same
+ * regardless of key order in the source artifact — the same discipline
+ * `resolved-bundle.ts` uses for `bundle_sha`. Callers MUST normalize the manifest
+ * ({@link normalizeManifest}) before hashing so incidental unknown keys never
+ * split the dedupe. Pure + dependency-free (node:crypto only).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promptTemplateSha = promptTemplateSha;
+const node_crypto_1 = require("node:crypto");
+/** Deterministic JSON: object keys sorted recursively, array order preserved.
+ * The same value always produces the same bytes, so the hash is stable across
+ * processes. Mirrors resolved-bundle.ts's canonicalize (kept local so the two
+ * hashers stay independently auditable). */
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = canonicalize(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * The content-hash id of a prompt version — `sha256:<hex>`, self-describing so a
+ * future algorithm change is visible in the stored value rather than silent
+ * (parity with `hashResolvedBundle`). The template is hashed verbatim; the
+ * manifest is canonicalized. The two are joined with a NUL separator that cannot
+ * appear in the template, so no `(template, manifest)` pair can collide with a
+ * different pair by boundary ambiguity.
+ */
+function promptTemplateSha(template, manifest) {
+    const canonicalManifest = JSON.stringify(canonicalize(manifest));
+    const hash = (0, node_crypto_1.createHash)("sha256");
+    hash.update(template, "utf8");
+    hash.update("\0", "utf8");
+    hash.update(canonicalManifest, "utf8");
+    return `sha256:${hash.digest("hex")}`;
+}

package/dist/prompts-export-cli.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `modelrig prompts export` — PSR-3 (spec §3, the anti-lock-in gate).
+ *
+ *   modelrig prompts export --route <route> [--out modelrig/routes]
+ *       [--label prod | --version N] [--segment default] [--json]
+ *
+ * Fetches a prompt version from the ModelRig System-of-Record
+ * (`GET /v1/prompts/:route/export`, key-authed — a read needs only an org-scoped
+ * key) and writes its git files: the authored `template` to `<route>.md` and the
+ * assembly `manifest` to a sibling `<route>.manifest.json`, BYTE-FAITHFULLY. The
+ * command then PROVES the round-trip locally — it re-hashes the written files the
+ * way the store would (validate → normalize → hash) and checks the content id
+ * matches what ModelRig returned. ModelRig being your prompt's primary store
+ * never traps it in git.
+ *
+ * Goes through the API boundary (T12: the CLI never holds a DB client); the
+ * server scopes the read to the key's org (T11).
+ */
+import type { Flags } from "./cli";
+export declare function cmdPromptsExport(flags: Flags): Promise<number>;
+//# sourceMappingURL=prompts-export-cli.d.ts.map

package/dist/prompts-export-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts-export-cli.d.ts","sourceRoot":"","sources":["../src/prompts-export-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AA0CnC,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CA4EpE"}

package/dist/prompts-export-cli.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * `modelrig prompts export` — PSR-3 (spec §3, the anti-lock-in gate).
+ *
+ *   modelrig prompts export --route <route> [--out modelrig/routes]
+ *       [--label prod | --version N] [--segment default] [--json]
+ *
+ * Fetches a prompt version from the ModelRig System-of-Record
+ * (`GET /v1/prompts/:route/export`, key-authed — a read needs only an org-scoped
+ * key) and writes its git files: the authored `template` to `<route>.md` and the
+ * assembly `manifest` to a sibling `<route>.manifest.json`, BYTE-FAITHFULLY. The
+ * command then PROVES the round-trip locally — it re-hashes the written files the
+ * way the store would (validate → normalize → hash) and checks the content id
+ * matches what ModelRig returned. ModelRig being your prompt's primary store
+ * never traps it in git.
+ *
+ * Goes through the API boundary (T12: the CLI never holds a DB client); the
+ * server scopes the read to the key's org (T11).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdPromptsExport = cmdPromptsExport;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const config_1 = require("./config");
+const index_1 = require("./index");
+const DEFAULT_OUT = "modelrig/routes";
+function usage() {
+    return [
+        "usage: modelrig prompts export --route <route> [--out modelrig/routes]",
+        "                              [--label prod | --version N] [--segment default] [--json]",
+        "",
+        "Exports a prompt version from ModelRig back to git files (the anti-lock-in guarantee):",
+        "  <route>.md            the authored prompt template, verbatim",
+        "  <route>.manifest.json the assembly manifest (structure only)",
+        "A version re-created from these files carries the SAME content hash — proven after write.",
+        "",
+        "  MODELRIG_API_KEY    a rig_sk_ key in your org (a read needs no special scope)",
+        "  MODELRIG_INGEST_URL optional — the server base; defaults to the hosted API",
+    ].join("\n");
+}
+/** The content id a version re-created from the written files would carry — the
+ * store's write discipline (validate → normalize → hash) run locally, so the
+ * round-trip is proven without a second server call. */
+function recreatedSha(templateFile, manifestFile) {
+    let parsed;
+    try {
+        parsed = JSON.parse(manifestFile);
+    }
+    catch {
+        return null;
+    }
+    const validated = (0, index_1.validateManifest)(parsed);
+    if (!validated.ok)
+        return null;
+    return (0, index_1.promptTemplateSha)(templateFile, (0, index_1.normalizeManifest)(validated.manifest));
+}
+async function cmdPromptsExport(flags) {
+    // The subcommand token ("export") is flags.positional[0]; require it explicitly
+    // so `modelrig prompts` (no verb) prints usage rather than guessing.
+    if (flags.positional[0] !== "export") {
+        console.error(usage());
+        return 1;
+    }
+    const route = flags.named.get("route");
+    const out = flags.named.get("out") ?? DEFAULT_OUT;
+    const label = flags.named.get("label");
+    const versionRaw = flags.named.get("version");
+    const segment = flags.named.get("segment");
+    const asJson = flags.bare.has("json");
+    const exp = (0, config_1.loadConfigFromEnv)().export;
+    const api = exp !== undefined && exp.mode === "api" ? exp : undefined;
+    const base = api !== undefined ? new URL(api.ingestUrl).origin : "";
+    const key = api?.apiKey ?? "";
+    if (route === undefined || route === "" || base === "" || key === "") {
+        console.error(usage());
+        return 1;
+    }
+    const query = [];
+    if (versionRaw !== undefined && versionRaw !== "")
+        query.push(`version=${encodeURIComponent(versionRaw)}`);
+    else if (label !== undefined && label !== "")
+        query.push(`label=${encodeURIComponent(label)}`);
+    if (segment !== undefined && segment !== "")
+        query.push(`segment=${encodeURIComponent(segment)}`);
+    const suffix = query.length > 0 ? `?${query.join("&")}` : "";
+    let res;
+    try {
+        res = await fetch(`${base}/v1/prompts/${encodeURIComponent(route)}/export${suffix}`, {
+            headers: { authorization: `Bearer ${key}` },
+        });
+    }
+    catch (err) {
+        console.error(`prompts export: could not reach ${base}: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    const payload = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        console.error(`prompts export ${res.status}: ${[payload.error, payload.fix_hint].filter(Boolean).join(" — ") || "failed"}`);
+        return 1;
+    }
+    const files = payload.files ?? [];
+    if (files.length === 0 || payload.template_sha === undefined) {
+        console.error("prompts export: the server returned no files");
+        return 1;
+    }
+    // Write each file under --out, creating directories as needed.
+    const written = [];
+    for (const f of files) {
+        const dest = (0, node_path_1.join)(out, f.path);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(dest), { recursive: true });
+        (0, node_fs_1.writeFileSync)(dest, f.content);
+        written.push(dest);
+    }
+    // Prove the round-trip from the bytes on disk (never trust the transfer): the
+    // template file + the manifest file must re-hash to the server's content id.
+    const md = files.find((f) => f.path.endsWith(".md"));
+    const mf = files.find((f) => f.path.endsWith(".manifest.json"));
+    const rehashed = md !== undefined && mf !== undefined ? recreatedSha(md.content, mf.content) : null;
+    const roundTripped = rehashed !== null && rehashed === payload.template_sha;
+    if (asJson) {
+        console.log(JSON.stringify({ route: payload.route, version: payload.version, template_sha: payload.template_sha, written, round_trip: roundTripped }, null, 2));
+    }
+    else {
+        console.log(`Exported ${route} version ${String(payload.version)} → ${written.join(", ")}`);
+        console.log(roundTripped
+            ? `Round-trip verified: re-creating from these files reproduces the same content hash (${payload.template_sha.slice(0, 12)}…). Your prompt is not locked in.`
+            : "WARNING: the written files did NOT re-hash to the server's content id — do not rely on this export; re-run.");
+    }
+    return roundTripped ? 0 : 1;
+}

package/dist/query/grammar.d.ts

@@ -33,8 +33,8 @@
 import type { Classification, ColumnSource } from "./columns";
 export { describeAnalyticsSchema, evaluateAnalyticsQuery, planAnalyticsRead, ANALYTICS_SCAN_CAP, selectableColumnsAreMetaSafe, } from "./analytics";
 export type { AnalyticsSchema, AnalyticsSchemaField, AnalyticsResult, AnalyticsReadPlan, AnalyticsRow } from "./analytics";
-export { SAVED_QUERIES, savedQueryById, sinceIsoFor } from "./saved";
-export type { SavedQuery } from "./saved";
+export { SAVED_QUERIES, savedQueryById, sinceIsoFor, LAUNCH_COHORT_QUERIES, cohortQueryById } from "./saved";
+export type { SavedQuery, CohortQuery } from "./saved";
 export { DIMENSION_COLUMNS, METRIC_COLUMNS, RESERVED_DIMENSION_NAMES } from "./columns";
 export type { ColumnDef, Classification, ColumnSource } from "./columns";
 export declare class QueryGrammarError extends Error {

package/dist/query/grammar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/query/grammar.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/query/grammar.ts"],"names":[],"mappings":"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"}

package/dist/query/grammar.js

@@ -32,7 +32,7 @@
  * enum/number/boolean/hash/identifier/timestamp (columns.ts), never content.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QueryGrammarError = exports.RESERVED_DIMENSION_NAMES = exports.METRIC_COLUMNS = exports.DIMENSION_COLUMNS = exports.sinceIsoFor = exports.savedQueryById = exports.SAVED_QUERIES = exports.selectableColumnsAreMetaSafe = exports.ANALYTICS_SCAN_CAP = exports.planAnalyticsRead = exports.evaluateAnalyticsQuery = exports.describeAnalyticsSchema = void 0;
+exports.QueryGrammarError = exports.RESERVED_DIMENSION_NAMES = exports.METRIC_COLUMNS = exports.DIMENSION_COLUMNS = exports.cohortQueryById = exports.LAUNCH_COHORT_QUERIES = exports.sinceIsoFor = exports.savedQueryById = exports.SAVED_QUERIES = exports.selectableColumnsAreMetaSafe = exports.ANALYTICS_SCAN_CAP = exports.planAnalyticsRead = exports.evaluateAnalyticsQuery = exports.describeAnalyticsSchema = void 0;
 exports.parseQuery = parseQuery;
 exports.compileQuery = compileQuery;
 const columns_1 = require("./columns");
@@ -48,6 +48,8 @@ var saved_1 = require("./saved");
 Object.defineProperty(exports, "SAVED_QUERIES", { enumerable: true, get: function () { return saved_1.SAVED_QUERIES; } });
 Object.defineProperty(exports, "savedQueryById", { enumerable: true, get: function () { return saved_1.savedQueryById; } });
 Object.defineProperty(exports, "sinceIsoFor", { enumerable: true, get: function () { return saved_1.sinceIsoFor; } });
+Object.defineProperty(exports, "LAUNCH_COHORT_QUERIES", { enumerable: true, get: function () { return saved_1.LAUNCH_COHORT_QUERIES; } });
+Object.defineProperty(exports, "cohortQueryById", { enumerable: true, get: function () { return saved_1.cohortQueryById; } });
 var columns_2 = require("./columns");
 Object.defineProperty(exports, "DIMENSION_COLUMNS", { enumerable: true, get: function () { return columns_2.DIMENSION_COLUMNS; } });
 Object.defineProperty(exports, "METRIC_COLUMNS", { enumerable: true, get: function () { return columns_2.METRIC_COLUMNS; } });