modelrig 0.8.1 → 0.10.0

package/dist/prompts/manifest.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * PSR-1 — the assembly-manifest model (spec §2.1, authoring-guide §2–§3).
+ *
+ * A prompt in ModelRig is TWO things: the authored `template` text and the
+ * `manifest` — the ordered recipe for assembling the final prompt at call time.
+ * This module is the **structure-only** manifest: its `Slot[]` records HOW each
+ * part of the prompt is filled, never the filled value (the privacy guarantee —
+ * a `dynamic·tool` slot names `search_tickets`, never what it returned).
+ *
+ * PSR-1 is ZERO-DDL and validate-only: nothing here serves or stores a version.
+ * It exists to prove the model against real prompts (the InferWealth inference)
+ * and a hand-authored doc (ADJ-1) before PSR-2 builds the `prompt_versions`
+ * store. Pure + dependency-free (no YAML dep — the authoring doc is accepted as
+ * JSON per §7; YAML is an optional future add).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateManifest = validateManifest;
+exports.assertValidManifest = assertValidManifest;
+exports.normalizeManifest = normalizeManifest;
+exports.parseAuthoringDoc = parseAuthoringDoc;
+const DYNAMIC_KINDS = new Set([
+    "tool",
+    "cache",
+    "upstream",
+    "variable",
+]);
+const CACHE_POLICIES = new Set(["prefix", "none"]);
+const STATIC_FROMS = new Set(["system", "template"]);
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isNonEmptyString(v) {
+    return typeof v === "string" && v.length > 0;
+}
+/** Validate an untrusted value as a {@link Manifest} (spec §4). Rejects: an
+ * unknown slot kind, a `static` slot with BOTH or NEITHER `text`/`from`, a
+ * `dynamic` slot missing its `source` (or with a bad source kind / empty ref /
+ * bad cache_policy), a slot carrying fields of the wrong kind, and duplicate
+ * slot ids. Never throws — returns a result. */
+function validateManifest(input) {
+    const errors = [];
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["manifest must be an object with a `slots` array"] };
+    }
+    const slots = input["slots"];
+    if (!Array.isArray(slots)) {
+        return { ok: false, errors: ["manifest.slots must be an array"] };
+    }
+    const seenIds = new Set();
+    slots.forEach((raw, i) => {
+        const at = `slots[${i}]`;
+        if (!isRecord(raw)) {
+            errors.push(`${at} must be an object`);
+            return;
+        }
+        const id = raw["id"];
+        if (!isNonEmptyString(id)) {
+            errors.push(`${at}.id must be a non-empty string`);
+        }
+        else if (seenIds.has(id)) {
+            errors.push(`${at}.id "${id}" is a duplicate — slot ids must be unique`);
+        }
+        else {
+            seenIds.add(id);
+        }
+        const kind = raw["kind"];
+        const hasText = raw["text"] !== undefined;
+        const hasFrom = raw["from"] !== undefined;
+        const hasSource = raw["source"] !== undefined;
+        if (kind === "static") {
+            if (hasSource)
+                errors.push(`${at} is static but carries a dynamic \`source\``);
+            if (hasText && hasFrom) {
+                errors.push(`${at} static slot has BOTH \`text\` and \`from\` — exactly one is allowed`);
+            }
+            else if (!hasText && !hasFrom) {
+                errors.push(`${at} static slot has NEITHER \`text\` nor \`from\` — exactly one is required`);
+            }
+            else if (hasText && typeof raw["text"] !== "string") {
+                errors.push(`${at}.text must be a string`);
+            }
+            else if (hasFrom && !STATIC_FROMS.has(raw["from"])) {
+                errors.push(`${at}.from must be one of system, template`);
+            }
+        }
+        else if (kind === "dynamic") {
+            if (hasText || hasFrom) {
+                errors.push(`${at} is dynamic but carries static \`text\`/\`from\``);
+            }
+            if (!hasSource) {
+                errors.push(`${at} dynamic slot is missing its \`source\``);
+            }
+            else {
+                validateSource(raw["source"], at, errors);
+            }
+        }
+        else {
+            errors.push(`${at}.kind must be one of static, dynamic (got ${JSON.stringify(kind)})`);
+        }
+    });
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, manifest: { slots: slots } };
+}
+function validateSource(source, at, errors) {
+    if (!isRecord(source)) {
+        errors.push(`${at}.source must be an object`);
+        return;
+    }
+    if (!DYNAMIC_KINDS.has(source["kind"])) {
+        errors.push(`${at}.source.kind must be one of tool, cache, upstream, variable`);
+    }
+    if (!isNonEmptyString(source["ref"])) {
+        errors.push(`${at}.source.ref must be a non-empty string`);
+    }
+    if (source["cache_policy"] !== undefined && !CACHE_POLICIES.has(source["cache_policy"])) {
+        errors.push(`${at}.source.cache_policy must be one of prefix, none`);
+    }
+}
+/** Throwing form of {@link validateManifest} — returns the narrowed manifest or
+ * throws with the joined error list. Use where an invalid manifest is a bug the
+ * caller wants surfaced (tests, the emit path's guard). */
+function assertValidManifest(input) {
+    const result = validateManifest(input);
+    if (!result.ok) {
+        throw new Error(`invalid manifest: ${result.errors.join("; ")}`);
+    }
+    return result.manifest;
+}
+/**
+ * Reduce a validated {@link Manifest} to ITS CANONICAL SHAPE — the ONE clean
+ * projection PSR-2 persists (spec §4 "re-validate + normalize on ingest").
+ *
+ * WHY (a PSR-1 QA finding): {@link validateManifest} NARROWS an untrusted value
+ * to `Manifest` but casts `slots as Slot[]` — it does NOT strip unknown keys, so
+ * a raw artifact blob can carry extra fields (`text` alongside a `from`, a stray
+ * `note`, a `source` on a static slot) that pass validation and would be stored
+ * verbatim. The ingest path (prompt-ingest.ts) must NEVER trust the artifact blob
+ * as-is: it re-validates AND normalizes here so `template_sha` (computed over the
+ * normalized manifest) is stable — identical content always dedupes to one row,
+ * regardless of incidental key noise in the source artifact.
+ *
+ * Each slot is rebuilt from scratch keeping ONLY the canonical keys:
+ *   static  → { id, kind, text }  XOR  { id, kind, from }
+ *   dynamic → { id, kind, source: { kind, ref, cache_policy? } }
+ * Slot order is preserved (order = send order, D6). The rebuilt manifest is
+ * re-validated ({@link assertValidManifest}) so a caller that skipped validation
+ * still cannot persist a malformed shape.
+ */
+function normalizeManifest(input) {
+    const slots = input.slots.map((slot) => {
+        if (slot.kind === "static") {
+            // text XOR from — validation guarantees exactly one is present.
+            if (slot.text !== undefined) {
+                return { id: slot.id, kind: "static", text: slot.text };
+            }
+            return { id: slot.id, kind: "static", from: slot.from };
+        }
+        const src = slot.source;
+        const source = src.cache_policy !== undefined
+            ? { kind: src.kind, ref: src.ref, cache_policy: src.cache_policy }
+            : { kind: src.kind, ref: src.ref };
+        return { id: slot.id, kind: "dynamic", source };
+    });
+    return assertValidManifest({ slots });
+}
+/**
+ * ADJ-1 — the "author from scratch" on-ramp. Parse a declared authoring doc
+ * (authoring-guide §3) into a validated {@link Manifest}. Accepts the doc as a
+ * JSON string OR an already-parsed object (§7: the MCP tool takes JSON; YAML is
+ * an optional future add and is NOT parsed here — a YAML string throws a
+ * teaching error). Beyond {@link validateManifest} it cross-checks that every
+ * `static` slot's `from: system|template` resolves to a present top-level field,
+ * so an author cannot reference authored text the doc does not carry.
+ *
+ * Structure-only: the returned manifest's slots are the authored slots verbatim
+ * (a `from`-slot keeps its `from`; the authored text is NOT inlined), so
+ * `parseAuthoringDoc` round-trips a hand-authored doc.
+ */
+function parseAuthoringDoc(input) {
+    let doc = input;
+    if (typeof input === "string") {
+        try {
+            doc = JSON.parse(input);
+        }
+        catch (err) {
+            throw new Error("authoring doc must be JSON (YAML is not parsed here — pass JSON per authoring-guide §7): " +
+                (err instanceof Error ? err.message : String(err)));
+        }
+    }
+    if (!isRecord(doc)) {
+        throw new Error("authoring doc must be an object");
+    }
+    const manifestBlock = doc["manifest"];
+    if (!isRecord(manifestBlock)) {
+        throw new Error("authoring doc is missing a `manifest` block");
+    }
+    const manifest = assertValidManifest(manifestBlock);
+    // ADJ-1 cross-check: a `from` slot must reference a present authored field.
+    const hasSystem = typeof doc["system"] === "string";
+    const hasTemplate = typeof doc["template"] === "string";
+    const missing = [];
+    for (const slot of manifest.slots) {
+        if (slot.from === "system" && !hasSystem)
+            missing.push(`slot "${slot.id}" references \`system\``);
+        if (slot.from === "template" && !hasTemplate)
+            missing.push(`slot "${slot.id}" references \`template\``);
+    }
+    if (missing.length > 0) {
+        throw new Error(`authoring doc has \`from\` slots with no matching authored field: ${missing.join("; ")}`);
+    }
+    return manifest;
+}

package/dist/prompts/prompt-fetch.d.ts

@@ -0,0 +1,84 @@
+/**
+ * PSR-2b — SDK fetch-by-label + the content-addressed prompt cache (spec §3
+ * "SDK read", §4). The remote half of serving a prompt by its movable `prod`
+ * label.
+ *
+ * The gateway already serves the promoted version's template+manifest through
+ * `routes.bundle` (PSR-2a's write-through). This module adds the OPTIONAL
+ * explicit read the SDK uses when it wants a prompt by label directly:
+ *   GET /v1/prompts/:route?label=prod   (key-auth, org-scoped)
+ *     → { version, template, manifest, template_sha }
+ *   ETag: <template_sha>                (304 Not Modified when it matches)
+ *
+ * The fetcher mirrors `call-config.ts`'s leak discipline: header-only auth, no
+ * body/URL in an error (C2), and it NEVER throws — a network/HTTP failure
+ * resolves `null`, a 304 resolves `"not-modified"`, a malformed 200 resolves
+ * `null`. So the fail-open resolver ({@link ./prompt-resolve}) always stays
+ * fail-open around it.
+ *
+ * The cache is CONTENT-ADDRESSED, keyed `label+template_sha` (spec §3): the
+ * same served content is one entry regardless of how many times it is fetched,
+ * and a per-(route,label) pointer records the last-known-good sha — the tier the
+ * resolver falls back to when the control plane is unreachable.
+ */
+import { type Manifest } from "./manifest";
+/** A prompt served by label — the explicit endpoint's body and the unit the
+ * client cache holds. `template_sha` is both the content id and the ETag. */
+export interface ServedPrompt {
+    readonly version: number;
+    readonly template: string;
+    readonly manifest: Manifest;
+    readonly template_sha: string;
+}
+/** Pulls one route's prompt for a label, ETag-aware. Returns the prompt, `"not-
+ * modified"` (304 — keep the cache), or `null` (miss/error — the resolver keeps
+ * last-known-good). NEVER throws. */
+export interface PromptFetcher {
+    fetch(route: string, label: string, etag: string | undefined): Promise<ServedPrompt | "not-modified" | null>;
+}
+/**
+ * Narrow an untrusted endpoint body into a {@link ServedPrompt}, or null when the
+ * shape is not what the endpoint promises (a malformed 200 is a miss, never
+ * trusted — we never fabricate a served prompt from junk). The manifest is
+ * validated with the shared {@link validateManifest} so a structurally-broken
+ * manifest can never reach the client-fill engine.
+ */
+export declare function parseServedPrompt(body: unknown): ServedPrompt | null;
+/**
+ * The content-addressed prompt cache (spec §3). Holds served content keyed
+ * `label+template_sha`, plus a per-(route,label) pointer to the last-known-good
+ * sha. `put` stores the content AND advances the pointer (a fetched version is
+ * now the last-known-good); `lastKnown` reads the current content for a label —
+ * the fail-open tier the resolver serves when a fetch cannot complete.
+ */
+export interface PromptCache {
+    /** The served content for an exact (route,label,sha), if held. */
+    get(route: string, label: string, sha: string): ServedPrompt | undefined;
+    /** The last-known-good served content for (route,label), if any has landed. */
+    lastKnown(route: string, label: string): ServedPrompt | undefined;
+    /** The last-known-good sha for (route,label) — the ETag to revalidate with. */
+    lastKnownSha(route: string, label: string): string | undefined;
+    /** Store content and advance the last-known-good pointer to its sha. */
+    put(route: string, label: string, prompt: ServedPrompt): void;
+}
+/** Build an empty {@link PromptCache}. One per rig. In-memory only — a prompt
+ * cache is a per-process convenience, never durable state. */
+export declare function createPromptCache(): PromptCache;
+export interface ApiPromptFetcherConfig {
+    /** Base URL of the hosted control plane — the SAME `ingestUrl` the api sink
+     * and call-config fetcher use (the prompt path hangs off the host). */
+    readonly ingestUrl: string;
+    /** `rig_sk_…` key. A read rides the readable route + prompt rows; header only,
+     * never a URL (C2). */
+    readonly apiKey: string;
+    readonly fetchFn?: typeof fetch;
+}
+/**
+ * The api-mode prompt fetcher: one authenticated, ETag-aware GET per (route,
+ * label). Mirrors the api sink's leak discipline (status only, never the
+ * body/URL in an error — C2). NEVER throws: a network/HTTP failure resolves
+ * null, a 304 resolves "not-modified", a malformed 200 resolves null — so the
+ * resolver stays fail-open.
+ */
+export declare function createApiPromptFetcher(config: ApiPromptFetcherConfig): PromptFetcher;
+//# sourceMappingURL=prompt-fetch.d.ts.map

package/dist/prompts/prompt-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-fetch.d.ts","sourceRoot":"","sources":["../../src/prompts/prompt-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE7D;6EAC6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;qCAEqC;AACrC,MAAM,WAAW,aAAa;IAC5B,KAAK,CACH,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAAC,YAAY,GAAG,cAAc,GAAG,IAAI,CAAC,CAAC;CAClD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CAcpE;AAYD;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IACzE,+EAA+E;IAC/E,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IAClE,+EAA+E;IAC/E,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC/D,wEAAwE;IACxE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;CAC/D;AAED;8DAC8D;AAC9D,wBAAgB,iBAAiB,IAAI,WAAW,CAmB/C;AAED,MAAM,WAAW,sBAAsB;IACrC;2EACuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;2BACuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,sBAAsB,GAAG,aAAa,CA4BpF"}

package/dist/prompts/prompt-fetch.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * PSR-2b — SDK fetch-by-label + the content-addressed prompt cache (spec §3
+ * "SDK read", §4). The remote half of serving a prompt by its movable `prod`
+ * label.
+ *
+ * The gateway already serves the promoted version's template+manifest through
+ * `routes.bundle` (PSR-2a's write-through). This module adds the OPTIONAL
+ * explicit read the SDK uses when it wants a prompt by label directly:
+ *   GET /v1/prompts/:route?label=prod   (key-auth, org-scoped)
+ *     → { version, template, manifest, template_sha }
+ *   ETag: <template_sha>                (304 Not Modified when it matches)
+ *
+ * The fetcher mirrors `call-config.ts`'s leak discipline: header-only auth, no
+ * body/URL in an error (C2), and it NEVER throws — a network/HTTP failure
+ * resolves `null`, a 304 resolves `"not-modified"`, a malformed 200 resolves
+ * `null`. So the fail-open resolver ({@link ./prompt-resolve}) always stays
+ * fail-open around it.
+ *
+ * The cache is CONTENT-ADDRESSED, keyed `label+template_sha` (spec §3): the
+ * same served content is one entry regardless of how many times it is fetched,
+ * and a per-(route,label) pointer records the last-known-good sha — the tier the
+ * resolver falls back to when the control plane is unreachable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseServedPrompt = parseServedPrompt;
+exports.createPromptCache = createPromptCache;
+exports.createApiPromptFetcher = createApiPromptFetcher;
+const manifest_1 = require("./manifest");
+/**
+ * Narrow an untrusted endpoint body into a {@link ServedPrompt}, or null when the
+ * shape is not what the endpoint promises (a malformed 200 is a miss, never
+ * trusted — we never fabricate a served prompt from junk). The manifest is
+ * validated with the shared {@link validateManifest} so a structurally-broken
+ * manifest can never reach the client-fill engine.
+ */
+function parseServedPrompt(body) {
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return null;
+    const b = body;
+    if (typeof b.version !== "number" || !Number.isInteger(b.version))
+        return null;
+    if (typeof b.template !== "string")
+        return null;
+    if (typeof b.template_sha !== "string" || b.template_sha === "")
+        return null;
+    const validation = (0, manifest_1.validateManifest)(b.manifest);
+    if (!validation.ok)
+        return null;
+    return {
+        version: b.version,
+        template: b.template,
+        manifest: validation.manifest,
+        template_sha: b.template_sha,
+    };
+}
+const KEY_SEP = "\0"; // NUL — cannot appear in a route/label/sha identifier.
+function contentKey(route, label, sha) {
+    return `${route}${KEY_SEP}${label}${KEY_SEP}${sha}`;
+}
+function pointerKey(route, label) {
+    return `${route}${KEY_SEP}${label}`;
+}
+/** Build an empty {@link PromptCache}. One per rig. In-memory only — a prompt
+ * cache is a per-process convenience, never durable state. */
+function createPromptCache() {
+    const content = new Map();
+    const pointer = new Map(); // (route,label) → last-known-good sha
+    return {
+        get(route, label, sha) {
+            return content.get(contentKey(route, label, sha));
+        },
+        lastKnown(route, label) {
+            const sha = pointer.get(pointerKey(route, label));
+            return sha === undefined ? undefined : content.get(contentKey(route, label, sha));
+        },
+        lastKnownSha(route, label) {
+            return pointer.get(pointerKey(route, label));
+        },
+        put(route, label, prompt) {
+            content.set(contentKey(route, label, prompt.template_sha), prompt);
+            pointer.set(pointerKey(route, label), prompt.template_sha);
+        },
+    };
+}
+/**
+ * The api-mode prompt fetcher: one authenticated, ETag-aware GET per (route,
+ * label). Mirrors the api sink's leak discipline (status only, never the
+ * body/URL in an error — C2). NEVER throws: a network/HTTP failure resolves
+ * null, a 304 resolves "not-modified", a malformed 200 resolves null — so the
+ * resolver stays fail-open.
+ */
+function createApiPromptFetcher(config) {
+    const base = config.ingestUrl.replace(/\/$/, "");
+    const fetchFn = config.fetchFn ?? fetch;
+    return {
+        async fetch(route, label, etag) {
+            const url = `${base}/v1/prompts/${encodeURIComponent(route)}?label=${encodeURIComponent(label)}`;
+            let response;
+            try {
+                response = await fetchFn(url, {
+                    method: "GET",
+                    headers: {
+                        authorization: `Bearer ${config.apiKey}`,
+                        ...(etag !== undefined ? { "if-none-match": etag } : {}),
+                    },
+                });
+            }
+            catch {
+                return null; // network throw — fail-open, keep last-known.
+            }
+            if (response.status === 304)
+                return "not-modified";
+            if (!response.ok)
+                return null;
+            const body = (await response.json().catch(() => null));
+            return parseServedPrompt(body);
+        },
+    };
+}

package/dist/prompts/prompt-resolve.d.ts

@@ -0,0 +1,76 @@
+/**
+ * PSR-2b — the fail-open prompt resolver (spec §4 "Fail-open", HARD requirement).
+ *
+ * The template fetch is the ONLY remote part of serving a prompt; the SDK stays
+ * in-process. A control-plane blip must NEVER block a call, so this resolver
+ * degrades exactly like the artifact namespace already does — through named
+ * tiers, in order:
+ *
+ *   1. cache-fresh    — within `ttlMs` of the last fetch, serve the cached
+ *                       last-known-good with no network at all.
+ *   2. fetch          — revalidate by ETag (`template_sha`); a new version is
+ *                       cached and served, a 304 keeps the cache.
+ *   3. last-known-good — the fetch failed/miss, but a version was fetched before:
+ *                       serve the cached last-known-good.
+ *   4. embedded        — never fetched successfully, and the fetch is failing:
+ *                       serve the embedded/pinned template (the last export or a
+ *                       bundled default) supplied by the app.
+ *
+ * If every tier is empty (never fetched, no embedded) the resolver returns
+ * `null` — "no PSR prompt; use your existing bundle serve path" (which itself
+ * fail-opens). So a call is never BLOCKED by the control plane: it is served the
+ * best template available, or falls through to the pre-PSR path.
+ *
+ * `resolve` NEVER throws. It is the fail-open envelope around the fetcher (which
+ * already never throws) and the cache (in-memory).
+ */
+import type { PromptCache, PromptFetcher, ServedPrompt } from "./prompt-fetch";
+/** Where a resolution came from — the served tier (spec §4). Surfaced so status
+ * / a test can prove which fail-open tier answered a call. */
+export type PromptServeSource = "cache" | "fetch" | "last-known-good" | "embedded";
+/** A resolved served prompt plus the tier that answered. */
+export interface ServedPromptResolution {
+    readonly prompt: ServedPrompt;
+    readonly source: PromptServeSource;
+}
+/**
+ * The embedded/pinned templates the app ships as the last-resort floor (spec
+ * §4: "the last export or a bundled default"). Keyed by (route,label); a `get`
+ * miss just means no floor for that label — the resolver returns null and the
+ * caller uses its existing bundle path.
+ */
+export interface EmbeddedPrompts {
+    get(route: string, label: string): ServedPrompt | undefined;
+}
+/** Build an {@link EmbeddedPrompts} from a plain in-memory table (the common
+ * case: a small set of bundled defaults or the last export the app pins). */
+export declare function createEmbeddedPrompts(table?: Readonly<Record<string, Readonly<Record<string, ServedPrompt>>>>): EmbeddedPrompts;
+export interface PromptResolverConfig {
+    readonly fetcher: PromptFetcher;
+    readonly cache: PromptCache;
+    /** The last-resort floor. Absent ⇒ tier 4 is empty (a cold fetch failure
+     * returns null ⇒ the caller's existing bundle path). */
+    readonly embedded?: EmbeddedPrompts;
+    /** Cache freshness window (spec §4, parity with call-config ~30–60s). Within
+     * it, no fetch — serve the cached last-known-good. */
+    readonly ttlMs: number;
+    /** Injectable clock for tests; defaults to Date.now. */
+    readonly now?: () => number;
+}
+export interface PromptResolver {
+    /**
+     * Resolve `route`'s prompt for `label`, fail-open through the tiers above.
+     * NEVER throws. Returns null only when every tier is empty (⇒ the caller
+     * serves its existing bundle, which itself fail-opens).
+     */
+    resolve(route: string, label: string): Promise<ServedPromptResolution | null>;
+}
+/**
+ * Build the fail-open prompt resolver (spec §4). Holds a per-(route,label) fetch
+ * timestamp so a read within `ttlMs` skips the network; a stale read revalidates
+ * by ETag and folds the result into the cache. Every failure path falls to the
+ * next tier — last-known-good, then embedded, then null — so a control-plane
+ * outage never blocks a call.
+ */
+export declare function createPromptResolver(config: PromptResolverConfig): PromptResolver;
+//# sourceMappingURL=prompt-resolve.d.ts.map

package/dist/prompts/prompt-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-resolve.d.ts","sourceRoot":"","sources":["../../src/prompts/prompt-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE/E;8DAC8D;AAC9D,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,GAAG,iBAAiB,GAAG,UAAU,CAAC;AAEnF,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;CAC7D;AAED;6EAC6E;AAC7E,wBAAgB,qBAAqB,CACnC,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAM,GAC3E,eAAe,CAMjB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B;4DACwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IACpC;0DACsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;CAC/E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CA+CjF"}

package/dist/prompts/prompt-resolve.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * PSR-2b — the fail-open prompt resolver (spec §4 "Fail-open", HARD requirement).
+ *
+ * The template fetch is the ONLY remote part of serving a prompt; the SDK stays
+ * in-process. A control-plane blip must NEVER block a call, so this resolver
+ * degrades exactly like the artifact namespace already does — through named
+ * tiers, in order:
+ *
+ *   1. cache-fresh    — within `ttlMs` of the last fetch, serve the cached
+ *                       last-known-good with no network at all.
+ *   2. fetch          — revalidate by ETag (`template_sha`); a new version is
+ *                       cached and served, a 304 keeps the cache.
+ *   3. last-known-good — the fetch failed/miss, but a version was fetched before:
+ *                       serve the cached last-known-good.
+ *   4. embedded        — never fetched successfully, and the fetch is failing:
+ *                       serve the embedded/pinned template (the last export or a
+ *                       bundled default) supplied by the app.
+ *
+ * If every tier is empty (never fetched, no embedded) the resolver returns
+ * `null` — "no PSR prompt; use your existing bundle serve path" (which itself
+ * fail-opens). So a call is never BLOCKED by the control plane: it is served the
+ * best template available, or falls through to the pre-PSR path.
+ *
+ * `resolve` NEVER throws. It is the fail-open envelope around the fetcher (which
+ * already never throws) and the cache (in-memory).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEmbeddedPrompts = createEmbeddedPrompts;
+exports.createPromptResolver = createPromptResolver;
+/** Build an {@link EmbeddedPrompts} from a plain in-memory table (the common
+ * case: a small set of bundled defaults or the last export the app pins). */
+function createEmbeddedPrompts(table = {}) {
+    return {
+        get(route, label) {
+            return table[route]?.[label];
+        },
+    };
+}
+/**
+ * Build the fail-open prompt resolver (spec §4). Holds a per-(route,label) fetch
+ * timestamp so a read within `ttlMs` skips the network; a stale read revalidates
+ * by ETag and folds the result into the cache. Every failure path falls to the
+ * next tier — last-known-good, then embedded, then null — so a control-plane
+ * outage never blocks a call.
+ */
+function createPromptResolver(config) {
+    const now = config.now ?? (() => Date.now());
+    const { fetcher, cache, embedded } = config;
+    const fetchedAt = new Map(); // (route,label) → last fetch ts
+    const stamp = (route, label) => `${route}\0${label}`;
+    /** The last-known-good or embedded floor, in that order, or null. */
+    function floor(route, label) {
+        const known = cache.lastKnown(route, label);
+        if (known !== undefined)
+            return { prompt: known, source: "last-known-good" };
+        const pinned = embedded?.get(route, label);
+        if (pinned !== undefined)
+            return { prompt: pinned, source: "embedded" };
+        return null;
+    }
+    return {
+        async resolve(route, label) {
+            const key = stamp(route, label);
+            const last = fetchedAt.get(key);
+            const cached = cache.lastKnown(route, label);
+            // Tier 1 — cache-fresh: within the TTL of a prior fetch, no network.
+            if (cached !== undefined && last !== undefined && now() - last < config.ttlMs) {
+                return { prompt: cached, source: "cache" };
+            }
+            try {
+                // Tier 2 — fetch, ETag-revalidated against the last-known-good sha.
+                const result = await fetcher.fetch(route, label, cache.lastKnownSha(route, label));
+                if (result === "not-modified") {
+                    fetchedAt.set(key, now());
+                    // 304 ⇒ the cached last-known-good is current.
+                    return floor(route, label);
+                }
+                if (result === null) {
+                    // Miss/error ⇒ tiers 3–4 (last-known-good, then embedded).
+                    return floor(route, label);
+                }
+                cache.put(route, label, result);
+                fetchedAt.set(key, now());
+                return { prompt: result, source: "fetch" };
+            }
+            catch {
+                // The hot path never throws — fall to the fail-open floor.
+                return floor(route, label);
+            }
+        },
+    };
+}