@warlock.js/ai 4.4.0 → 4.5.0

package/esm/prompts/prompts-manager.mjs

@@ -0,0 +1,410 @@
+import { InvalidRequestError } from "../errors/invalid-request-error.mjs";
+import "../errors/index.mjs";
+import { Instruction } from "../system-prompt/instruction.mjs";
+import { Persona } from "../system-prompt/persona.mjs";
+import { SystemPrompt } from "../system-prompt/system-prompt.mjs";
+import { describeContractTarget, findMissingPlaceholders, findUnreferencedRequired, judgePromptBodyCached } from "./prompts-validate.mjs";
+
+//#region ../@warlock.js/ai/src/prompts/prompts-manager.ts
+/**
+* Build the `name@version` registry key. Centralized so the duplicate check,
+* `get`, and `composedFrom` provenance all agree on one label shape.
+*/
+function promptKey(name, version) {
+	return `${name}@${version}`;
+}
+/**
+* Serialize a prompt's observable content — its ordered blocks (discriminator
+* + raw template text) — into a stable signature. Two prompts with the same
+* blocks in the same order share a signature, which is how `register()` tells
+* an idempotent re-registration from a genuine clash. Meta is intentionally
+* excluded: provenance / description should not defeat idempotency.
+*/
+function contentSignature(contract) {
+	return JSON.stringify(contract.blocks.map((block) => [block.type, block.text]));
+}
+/**
+* Reconstruct a block from its `{ type, text }` snapshot — `persona` blocks
+* become a `Persona`, everything else an `Instruction`. The inverse of the
+* flattening `export()` performs, so an imported registry resolves identically.
+*/
+function blockFromSnapshot(block) {
+	return block.type === "persona" ? new Persona(block.text) : new Instruction(block.text);
+}
+/**
+* Narrow a {@link PromptTemplateVersion} body to its ordered block list: a raw
+* string becomes one instruction block; an explicit block list is used verbatim.
+*/
+function blocksFromTemplate(template) {
+	if (typeof template === "string") return [new Instruction(template)];
+	return [...template];
+}
+/**
+* Concrete `PromptsManagerContract` — a single registry of named, versioned
+* `SystemPromptContract` builders keyed by `name@version`.
+*
+* **Role.** The store behind `ai.prompts`. It holds one flat
+* `Map<string, PromptsManagerEntry>` keyed by `name@version`, plus a monotonic
+* counter that stamps each entry's `addedAt` so "latest" is deterministic
+* (highest `addedAt` for a name) without ever reading the wall clock.
+*
+* **Responsibility.**
+* - Owns: the registry map, the `addedAt` counter, the duplicate /
+*   idempotency rule, default version derivation, latest selection, the
+*   per-version tag pins, and the validate / diff / export / import surface.
+* - Does NOT own: prompt rendering (delegated to the contract's `resolve()`),
+*   block composition, or the LLM-judge mechanics (delegated to the eval
+*   `judge` scorer via `prompts-validate`).
+*
+* Users construct via the `prompts()` factory — `new PromptsManager()` is not
+* the public API.
+*/
+var PromptsManager = class {
+	constructor(options = {}) {
+		this.entries = /* @__PURE__ */ new Map();
+		this.names = [];
+		this.pins = /* @__PURE__ */ new Map();
+		this.counter = 0;
+		this.judgeCache = options.judgeCache;
+	}
+	register(contract, options = {}) {
+		const meta = contract.meta();
+		const name = options.name ?? meta?.name;
+		if (!name) throw new InvalidRequestError("Cannot register a prompt without a name — set meta.name via systemPrompt(input, { name }) or .meta({ name }).", { context: { meta } });
+		const version = options.version ?? meta?.version ?? this.nextVersion(name);
+		const key = promptKey(name, version);
+		const existing = this.entries.get(key);
+		if (existing) {
+			if (contentSignature(existing.contract) === contentSignature(contract)) return this;
+			throw new InvalidRequestError(`A different prompt is already registered as "${key}".`, { context: {
+				name,
+				version
+			} });
+		}
+		if (!this.names.includes(name)) this.names.push(name);
+		this.entries.set(key, {
+			name,
+			version,
+			addedAt: this.counter++,
+			contract,
+			...options.tags ? { tags: options.tags } : {}
+		});
+		return this;
+	}
+	create(input, meta) {
+		if (input === void 0) return new SystemPrompt([], meta);
+		if (typeof input === "string") return new SystemPrompt([new Instruction(input)], meta);
+		return new SystemPrompt([...input], meta);
+	}
+	get(name, versionOrTag) {
+		return this.requireEntry(name, versionOrTag).contract;
+	}
+	has(name, versionOrTag) {
+		const { baseName, selector } = this.parseSelector(name, versionOrTag);
+		if (selector !== void 0) return this.resolveSelector(baseName, selector) !== void 0;
+		return this.latestEntry(baseName) !== void 0;
+	}
+	list() {
+		return [...this.names];
+	}
+	versions(name) {
+		return [...this.entries.values()].filter((entry) => entry.name === name).sort((a, b) => a.addedAt - b.addedAt).map((entry) => entry.version);
+	}
+	resolve(name, versionOrTag, placeholders) {
+		return this.requireEntry(name, versionOrTag).contract.resolve(placeholders);
+	}
+	define(name, versions) {
+		for (const entry of versions) {
+			const contract = new SystemPrompt(blocksFromTemplate(entry.template));
+			this.register(contract, {
+				name,
+				version: entry.version
+			});
+		}
+		return this;
+	}
+	tag(name, tag, version) {
+		if (!this.entries.has(promptKey(name, version))) throw new InvalidRequestError(`Cannot tag "${tag}" — no prompt registered as "${promptKey(name, version)}".`, { context: {
+			name,
+			tag,
+			version
+		} });
+		const nameTags = this.pins.get(name) ?? /* @__PURE__ */ new Map();
+		nameTags.set(tag, version);
+		this.pins.set(name, nameTags);
+		return this;
+	}
+	async validate(target, options = {}) {
+		const { text, required } = this.describeTarget(target);
+		const missing = findMissingPlaceholders(text, new Set(Object.keys(options.placeholders ?? {})), new Set([...required, ...options.declare ?? []]));
+		const unreferenced = findUnreferencedRequired(text, required);
+		const ok = missing.length === 0;
+		if (!options.judge) {
+			if (unreferenced.length === 0) return {
+				ok,
+				missing
+			};
+			return {
+				ok,
+				missing,
+				issues: unreferenced.map((key) => `Required key "${key}" is never referenced in the prompt.`)
+			};
+		}
+		const cache = options.judgeCache ?? this.judgeCache;
+		const judgeOutcome = await judgePromptBodyCached(text, options.judge, cache);
+		const issues = [...unreferenced.map((key) => `Required key "${key}" is never referenced in the prompt.`), ...judgeOutcome.issues];
+		return {
+			ok,
+			missing,
+			...judgeOutcome.score !== void 0 ? { score: judgeOutcome.score } : {},
+			issues
+		};
+	}
+	diff(name, from, to) {
+		const fromBlocks = this.snapshotBlocks(this.requireExact(name, from));
+		const toBlocks = this.snapshotBlocks(this.requireExact(name, to));
+		const added = [];
+		const removed = [];
+		const changed = [];
+		const max = Math.max(fromBlocks.length, toBlocks.length);
+		for (let index = 0; index < max; index++) {
+			const left = fromBlocks[index];
+			const right = toBlocks[index];
+			if (left && !right) {
+				removed.push(left);
+				continue;
+			}
+			if (!left && right) {
+				added.push(right);
+				continue;
+			}
+			if (left && right && (left.type !== right.type || left.text !== right.text)) changed.push({
+				from: left,
+				to: right
+			});
+		}
+		return {
+			name,
+			from,
+			to,
+			added,
+			removed,
+			changed,
+			identical: added.length === 0 && removed.length === 0 && changed.length === 0
+		};
+	}
+	export() {
+		return { prompts: this.names.map((name) => ({
+			name,
+			versions: this.versions(name).map((version) => this.exportVersion(name, version))
+		})) };
+	}
+	import(snapshot) {
+		for (const exported of snapshot.prompts) for (const version of exported.versions) {
+			const contract = new SystemPrompt(version.blocks.map(blockFromSnapshot), {
+				...version.description ? { description: version.description } : {},
+				...version.required ? { required: version.required } : {}
+			});
+			this.register(contract, {
+				name: exported.name,
+				version: version.version
+			});
+			for (const tag of version.tags ?? []) this.tag(exported.name, tag, version.version);
+		}
+		return this;
+	}
+	/**
+	* Flatten a registered version into its portable `{ version, blocks, tags?,
+	* description?, required? }` snapshot for `export()`.
+	*/
+	exportVersion(name, version) {
+		const entry = this.requireExact(name, version);
+		const meta = entry.contract.meta();
+		const tags = this.tagsForVersion(name, version);
+		return {
+			version,
+			blocks: this.snapshotBlocks(entry),
+			...tags.length > 0 ? { tags } : {},
+			...meta?.description ? { description: meta.description } : {},
+			...meta?.required ? { required: [...meta.required] } : {}
+		};
+	}
+	/** Every tag currently pinned to a specific `name@version`, in pin order. */
+	tagsForVersion(name, version) {
+		const nameTags = this.pins.get(name);
+		if (!nameTags) return [];
+		const tags = [];
+		for (const [tag, pinnedVersion] of nameTags) if (pinnedVersion === version) tags.push(tag);
+		return tags;
+	}
+	/** Flatten an entry's blocks to `{ type, text }` snapshots. */
+	snapshotBlocks(entry) {
+		return entry.contract.blocks.map((block) => ({
+			type: block.type,
+			text: block.text
+		}));
+	}
+	/**
+	* Resolve the body + declared-required keys for any `validate` target: a
+	* registered name (or `name@selector`), a `SystemPromptContract` instance, or
+	* a raw string.
+	*/
+	describeTarget(target) {
+		if (typeof target === "string") {
+			const { baseName, selector } = this.parseSelector(target, void 0);
+			const entry = selector ? this.resolveSelector(baseName, selector) : this.latestEntry(baseName);
+			if (entry) return describeContractTarget(entry.contract);
+			return {
+				text: target,
+				required: []
+			};
+		}
+		if (isSystemPromptContract(target)) return describeContractTarget(target);
+		if (isBlock(target)) return {
+			text: target.text,
+			required: []
+		};
+		throw new InvalidRequestError("validate() target must be a registered name, a SystemPromptContract, a prompt block, or a raw string.", { context: { target } });
+	}
+	/**
+	* The next integer version label for a name — `"1"` for the first, then the
+	* count of existing versions plus one. String-typed to match the free-form
+	* `version` label shape.
+	*/
+	nextVersion(name) {
+		const count = [...this.entries.values()].filter((entry) => entry.name === name).length;
+		return String(count + 1);
+	}
+	/** Pick the highest-`addedAt` entry for a name, or `undefined` when absent. */
+	latestEntry(name) {
+		let latest;
+		for (const entry of this.entries.values()) {
+			if (entry.name !== name) continue;
+			if (!latest || entry.addedAt > latest.addedAt) latest = entry;
+		}
+		return latest;
+	}
+	/**
+	* Split a name argument into its base name + optional selector. The selector
+	* comes from the explicit second argument when present, else from an inline
+	* `name@selector` in the first argument. A bare name yields no selector.
+	*/
+	parseSelector(name, versionOrTag) {
+		if (versionOrTag !== void 0) return {
+			baseName: name,
+			selector: versionOrTag
+		};
+		const at = name.indexOf("@");
+		if (at > 0) return {
+			baseName: name.slice(0, at),
+			selector: name.slice(at + 1)
+		};
+		return {
+			baseName: name,
+			selector: void 0
+		};
+	}
+	/**
+	* Resolve a selector (a version label OR a pinned tag) to a concrete entry.
+	* Version labels win over tags when both could match — the explicit label is
+	* the more specific intent. Returns `undefined` when neither resolves.
+	*/
+	resolveSelector(name, selector) {
+		const byVersion = this.entries.get(promptKey(name, selector));
+		if (byVersion) return byVersion;
+		const pinnedVersion = this.pins.get(name)?.get(selector);
+		if (pinnedVersion !== void 0) return this.entries.get(promptKey(name, pinnedVersion));
+	}
+	/**
+	* Resolve an entry by name (+ optional version / tag / inline selector),
+	* throwing {@link InvalidRequestError} when the name or the requested
+	* selector is unknown. The single lookup path `get` / `resolve` share.
+	*/
+	requireEntry(name, versionOrTag) {
+		const { baseName, selector } = this.parseSelector(name, versionOrTag);
+		if (selector !== void 0) {
+			const entry = this.resolveSelector(baseName, selector);
+			if (!entry) throw new InvalidRequestError(`No prompt registered as "${baseName}" with version/tag "${selector}".`, { context: {
+				name: baseName,
+				selector
+			} });
+			return entry;
+		}
+		const latest = this.latestEntry(baseName);
+		if (!latest) throw new InvalidRequestError(`No prompt registered under name "${baseName}".`, { context: { name: baseName } });
+		return latest;
+	}
+	/**
+	* Resolve a name + EXACT version label to its entry (no tag fallback), for
+	* `diff` / `export` where a concrete version is always required. Throws
+	* {@link InvalidRequestError} on a miss.
+	*/
+	requireExact(name, version) {
+		const entry = this.entries.get(promptKey(name, version));
+		if (!entry) throw new InvalidRequestError(`No prompt registered as "${promptKey(name, version)}".`, { context: {
+			name,
+			version
+		} });
+		return entry;
+	}
+};
+/**
+* Narrow an arbitrary value to a `SystemPromptContract` — true when it exposes
+* the builder surface (`blocks` array + a callable `resolve`) AND a callable
+* `meta`. Robust across duplicate package copies (no `instanceof`).
+*/
+function isSystemPromptContract(value) {
+	return typeof value === "object" && value !== null && Array.isArray(value.blocks) && typeof value.resolve === "function" && typeof value.meta === "function";
+}
+/**
+* Narrow an arbitrary value to a single `SystemPromptBlockContract` — true when
+* it carries a string `type` + `text` and a callable `resolve` but is NOT a
+* full prompt (no `blocks` array). Lets `validate` accept a lone block.
+*/
+function isBlock(value) {
+	return typeof value === "object" && value !== null && typeof value.type === "string" && typeof value.text === "string" && typeof value.resolve === "function";
+}
+/**
+* Create a new, isolated prompts manager.
+*
+* **Role.** Public factory for {@link PromptsManagerContract} — keeps
+* user-facing code free of `new` and consistent with the other `ai.*`
+* factories. Each call returns a fresh registry, so parallel test suites and
+* multi-tenant apps never share mutable global prompt state.
+*
+* The process-wide instance that named `systemPrompt(...)` builders
+* auto-register into is `ai.prompts` (see {@link defaultPromptsManager}).
+*
+* @param options - Optional wiring, notably a `judgeCache` that memoizes
+*   LLM-judge verdicts (absent ⇒ every judge pass runs live).
+*
+* @example
+* const registry = prompts();
+* registry.register(systemPrompt("You are support.", { name: "support" }));
+* registry.resolve("support"); // "You are support."
+*
+* @example
+* // Memoize judge verdicts across validations.
+* const registry = prompts({ judgeCache: new MemoryCacheDriver() });
+*/
+function prompts(options) {
+	return new PromptsManager(options);
+}
+/**
+* The process-wide default manager that named prompts auto-register into.
+*
+* Held as a module-level singleton (lazily created on first access) so
+* `system-prompt.ts` can register a named builder without importing the
+* `PromptsManager` class — keeping the auto-registration seam free of a
+* runtime import cycle.
+*/
+let defaultManager;
+/** Accessor for the process-wide default {@link PromptsManagerContract}. */
+function defaultPromptsManager() {
+	if (!defaultManager) defaultManager = new PromptsManager();
+	return defaultManager;
+}
+
+//#endregion
+export { defaultPromptsManager, promptKey, prompts };
+//# sourceMappingURL=prompts-manager.mjs.map

package/esm/prompts/prompts-manager.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts-manager.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/prompts/prompts-manager.ts"],"sourcesContent":["import type { Placeholders } from \"../contracts/placeholders.type\";\nimport type {\n  SystemPromptBlockContract,\n  SystemPromptContract,\n  SystemPromptMeta,\n} from \"../contracts/system-prompt.contract\";\nimport { InvalidRequestError } from \"../errors\";\nimport { Instruction } from \"../system-prompt/instruction\";\nimport { Persona } from \"../system-prompt/persona\";\nimport { SystemPrompt } from \"../system-prompt/system-prompt\";\nimport type {\n  PromptsManagerContract,\n  PromptsManagerEntry,\n  PromptsManagerRegisterOptions,\n} from \"./prompts-manager.contract\";\nimport type {\n  ExportedPromptVersion,\n  ExportedRegistry,\n  PromptDiff,\n  PromptDiffBlock,\n  PromptJudgeCacheLike,\n  PromptsManagerOptions,\n  PromptTemplateVersion,\n  PromptValidateTarget,\n  PromptValidationResult,\n  PromptsValidateOptions,\n} from \"./prompts-manager.type\";\nimport {\n  describeContractTarget,\n  findMissingPlaceholders,\n  findUnreferencedRequired,\n  judgePromptBodyCached,\n} from \"./prompts-validate\";\n\n/**\n * Build the `name@version` registry key. Centralized so the duplicate check,\n * `get`, and `composedFrom` provenance all agree on one label shape.\n */\nexport function promptKey(name: string, version: string): string {\n  return `${name}@${version}`;\n}\n\n/**\n * Serialize a prompt's observable content — its ordered blocks (discriminator\n * + raw template text) — into a stable signature. Two prompts with the same\n * blocks in the same order share a signature, which is how `register()` tells\n * an idempotent re-registration from a genuine clash. Meta is intentionally\n * excluded: provenance / description should not defeat idempotency.\n */\nfunction contentSignature(contract: SystemPromptContract): string {\n  return JSON.stringify(\n    contract.blocks.map(block => [block.type, block.text]),\n  );\n}\n\n/**\n * Reconstruct a block from its `{ type, text }` snapshot — `persona` blocks\n * become a `Persona`, everything else an `Instruction`. The inverse of the\n * flattening `export()` performs, so an imported registry resolves identically.\n */\nfunction blockFromSnapshot(block: PromptDiffBlock): SystemPromptBlockContract {\n  return block.type === \"persona\"\n    ? new Persona(block.text)\n    : new Instruction(block.text);\n}\n\n/**\n * Narrow a {@link PromptTemplateVersion} body to its ordered block list: a raw\n * string becomes one instruction block; an explicit block list is used verbatim.\n */\nfunction blocksFromTemplate(\n  template: string | readonly SystemPromptBlockContract[],\n): SystemPromptBlockContract[] {\n  if (typeof template === \"string\") {\n    return [new Instruction(template)];\n  }\n\n  return [...template];\n}\n\n/**\n * Concrete `PromptsManagerContract` — a single registry of named, versioned\n * `SystemPromptContract` builders keyed by `name@version`.\n *\n * **Role.** The store behind `ai.prompts`. It holds one flat\n * `Map<string, PromptsManagerEntry>` keyed by `name@version`, plus a monotonic\n * counter that stamps each entry's `addedAt` so \"latest\" is deterministic\n * (highest `addedAt` for a name) without ever reading the wall clock.\n *\n * **Responsibility.**\n * - Owns: the registry map, the `addedAt` counter, the duplicate /\n *   idempotency rule, default version derivation, latest selection, the\n *   per-version tag pins, and the validate / diff / export / import surface.\n * - Does NOT own: prompt rendering (delegated to the contract's `resolve()`),\n *   block composition, or the LLM-judge mechanics (delegated to the eval\n *   `judge` scorer via `prompts-validate`).\n *\n * Users construct via the `prompts()` factory — `new PromptsManager()` is not\n * the public API.\n */\nclass PromptsManager implements PromptsManagerContract {\n  /** Flat registry keyed by `name@version`. */\n  private readonly entries = new Map<string, PromptsManagerEntry>();\n\n  /** First-seen order of names, for a stable `list()`. */\n  private readonly names: string[] = [];\n\n  /** Per-name tag pins: `name` → (`tag` → `version`). */\n  private readonly pins = new Map<string, Map<string, string>>();\n\n  /** Optional process-level judge-verdict memo (absent ⇒ judge always runs live). */\n  private readonly judgeCache?: PromptJudgeCacheLike;\n\n  /** Monotonic insertion counter — the deterministic stand-in for a timestamp. */\n  private counter = 0;\n\n  public constructor(options: PromptsManagerOptions = {}) {\n    this.judgeCache = options.judgeCache;\n  }\n\n  public register(\n    contract: SystemPromptContract,\n    options: PromptsManagerRegisterOptions = {},\n  ): PromptsManagerContract {\n    const meta = contract.meta();\n    // An explicit override (from define() / import()) wins over the contract's\n    // own meta — it lets those bulk paths register an anonymous contract under\n    // a name without the SystemPrompt constructor's default-manager auto-reg.\n    const name = options.name ?? meta?.name;\n\n    if (!name) {\n      throw new InvalidRequestError(\n        \"Cannot register a prompt without a name — set meta.name via \" +\n          \"systemPrompt(input, { name }) or .meta({ name }).\",\n        { context: { meta } },\n      );\n    }\n\n    const version =\n      options.version ?? meta?.version ?? this.nextVersion(name);\n    const key = promptKey(name, version);\n    const existing = this.entries.get(key);\n\n    if (existing) {\n      // Idempotent re-registration: identical content under the same\n      // name@version is a no-op, not an error. Anything else is a clash.\n      if (contentSignature(existing.contract) === contentSignature(contract)) {\n        return this;\n      }\n\n      throw new InvalidRequestError(\n        `A different prompt is already registered as \"${key}\".`,\n        { context: { name, version } },\n      );\n    }\n\n    if (!this.names.includes(name)) {\n      this.names.push(name);\n    }\n\n    this.entries.set(key, {\n      name,\n      version,\n      addedAt: this.counter++,\n      contract,\n      ...(options.tags ? { tags: options.tags } : {}),\n    });\n\n    return this;\n  }\n\n  public create(\n    input?: string | ReadonlyArray<SystemPromptBlockContract>,\n    meta?: SystemPromptMeta,\n  ): SystemPromptContract {\n    // Mirror `systemPromptFactory` exactly (no import — `system-prompt.ts`\n    // already depends on this module, so importing its factory back here would\n    // close an import cycle). A name in `meta` auto-registers into the\n    // process-wide default manager via the SystemPrompt constructor.\n    if (input === undefined) {\n      return new SystemPrompt([], meta);\n    }\n\n    if (typeof input === \"string\") {\n      return new SystemPrompt([new Instruction(input)], meta);\n    }\n\n    return new SystemPrompt([...input], meta);\n  }\n\n  public get(name: string, versionOrTag?: string): SystemPromptContract {\n    return this.requireEntry(name, versionOrTag).contract;\n  }\n\n  public has(name: string, versionOrTag?: string): boolean {\n    const { baseName, selector } = this.parseSelector(name, versionOrTag);\n\n    if (selector !== undefined) {\n      return this.resolveSelector(baseName, selector) !== undefined;\n    }\n\n    return this.latestEntry(baseName) !== undefined;\n  }\n\n  public list(): string[] {\n    return [...this.names];\n  }\n\n  public versions(name: string): string[] {\n    return [...this.entries.values()]\n      .filter(entry => entry.name === name)\n      .sort((a, b) => a.addedAt - b.addedAt)\n      .map(entry => entry.version);\n  }\n\n  public resolve(\n    name: string,\n    versionOrTag?: string,\n    placeholders?: Placeholders,\n  ): string {\n    return this.requireEntry(name, versionOrTag).contract.resolve(placeholders);\n  }\n\n  public define(\n    name: string,\n    versions: readonly PromptTemplateVersion[],\n  ): PromptsManagerContract {\n    for (const entry of versions) {\n      const blocks = blocksFromTemplate(entry.template);\n      // Anonymous contract (no name in meta ⇒ no SystemPrompt constructor\n      // auto-registration into the default manager); the name/version are\n      // supplied explicitly so define() targets only THIS manager.\n      const contract = new SystemPrompt(blocks);\n\n      this.register(contract, { name, version: entry.version });\n    }\n\n    return this;\n  }\n\n  public tag(\n    name: string,\n    tag: string,\n    version: string,\n  ): PromptsManagerContract {\n    // Validate the target exists before pinning — a tag to a missing version is\n    // an authoring mistake, not a silent dangling pin.\n    if (!this.entries.has(promptKey(name, version))) {\n      throw new InvalidRequestError(\n        `Cannot tag \"${tag}\" — no prompt registered as \"${promptKey(\n          name,\n          version,\n        )}\".`,\n        { context: { name, tag, version } },\n      );\n    }\n\n    const nameTags = this.pins.get(name) ?? new Map<string, string>();\n    nameTags.set(tag, version);\n    this.pins.set(name, nameTags);\n\n    return this;\n  }\n\n  public async validate(\n    target: PromptValidateTarget,\n    options: PromptsValidateOptions = {},\n  ): Promise<PromptValidationResult> {\n    const { text, required } = this.describeTarget(target);\n\n    const provided = new Set(Object.keys(options.placeholders ?? {}));\n    const declared = new Set<string>([\n      ...required,\n      ...(options.declare ?? []),\n    ]);\n\n    const missing = findMissingPlaceholders(text, provided, declared);\n\n    // A declared-required key that the body never references is itself a\n    // defect — surface it as an issue (it does not affect `missing` / `ok`,\n    // which track unresolved placeholders).\n    const unreferenced = findUnreferencedRequired(text, required);\n\n    const ok = missing.length === 0;\n\n    if (!options.judge) {\n      if (unreferenced.length === 0) {\n        return { ok, missing };\n      }\n\n      return {\n        ok,\n        missing,\n        issues: unreferenced.map(\n          key => `Required key \"${key}\" is never referenced in the prompt.`,\n        ),\n      };\n    }\n\n    // Per-call cache override wins over the manager-level memo.\n    const cache = options.judgeCache ?? this.judgeCache;\n    const judgeOutcome = await judgePromptBodyCached(text, options.judge, cache);\n\n    const issues = [\n      ...unreferenced.map(\n        key => `Required key \"${key}\" is never referenced in the prompt.`,\n      ),\n      ...judgeOutcome.issues,\n    ];\n\n    return {\n      ok,\n      missing,\n      ...(judgeOutcome.score !== undefined ? { score: judgeOutcome.score } : {}),\n      issues,\n    };\n  }\n\n  public diff(name: string, from: string, to: string): PromptDiff {\n    const fromBlocks = this.snapshotBlocks(this.requireExact(name, from));\n    const toBlocks = this.snapshotBlocks(this.requireExact(name, to));\n\n    const added: PromptDiffBlock[] = [];\n    const removed: PromptDiffBlock[] = [];\n    const changed: { from: PromptDiffBlock; to: PromptDiffBlock }[] = [];\n\n    const max = Math.max(fromBlocks.length, toBlocks.length);\n\n    for (let index = 0; index < max; index++) {\n      const left = fromBlocks[index];\n      const right = toBlocks[index];\n\n      if (left && !right) {\n        removed.push(left);\n        continue;\n      }\n\n      if (!left && right) {\n        added.push(right);\n        continue;\n      }\n\n      if (left && right && (left.type !== right.type || left.text !== right.text)) {\n        changed.push({ from: left, to: right });\n      }\n    }\n\n    return {\n      name,\n      from,\n      to,\n      added,\n      removed,\n      changed,\n      identical:\n        added.length === 0 && removed.length === 0 && changed.length === 0,\n    };\n  }\n\n  public export(): ExportedRegistry {\n    return {\n      prompts: this.names.map(name => ({\n        name,\n        versions: this.versions(name).map(version =>\n          this.exportVersion(name, version),\n        ),\n      })),\n    };\n  }\n\n  public import(snapshot: ExportedRegistry): PromptsManagerContract {\n    for (const exported of snapshot.prompts) {\n      for (const version of exported.versions) {\n        const blocks = version.blocks.map(blockFromSnapshot);\n        // Anonymous (no `name` in meta) so the SystemPrompt constructor does\n        // not auto-register into the default manager; description / required\n        // ride along for round-trip fidelity. Name/version are explicit so the\n        // import lands only on THIS manager.\n        const contract = new SystemPrompt(blocks, {\n          ...(version.description ? { description: version.description } : {}),\n          ...(version.required ? { required: version.required } : {}),\n        });\n\n        this.register(contract, {\n          name: exported.name,\n          version: version.version,\n        });\n\n        for (const tag of version.tags ?? []) {\n          this.tag(exported.name, tag, version.version);\n        }\n      }\n    }\n\n    return this;\n  }\n\n  /**\n   * Flatten a registered version into its portable `{ version, blocks, tags?,\n   * description?, required? }` snapshot for `export()`.\n   */\n  private exportVersion(name: string, version: string): ExportedPromptVersion {\n    const entry = this.requireExact(name, version);\n    const meta = entry.contract.meta();\n    const tags = this.tagsForVersion(name, version);\n\n    return {\n      version,\n      blocks: this.snapshotBlocks(entry),\n      ...(tags.length > 0 ? { tags } : {}),\n      ...(meta?.description ? { description: meta.description } : {}),\n      ...(meta?.required ? { required: [...meta.required] } : {}),\n    };\n  }\n\n  /** Every tag currently pinned to a specific `name@version`, in pin order. */\n  private tagsForVersion(name: string, version: string): string[] {\n    const nameTags = this.pins.get(name);\n\n    if (!nameTags) {\n      return [];\n    }\n\n    const tags: string[] = [];\n\n    for (const [tag, pinnedVersion] of nameTags) {\n      if (pinnedVersion === version) {\n        tags.push(tag);\n      }\n    }\n\n    return tags;\n  }\n\n  /** Flatten an entry's blocks to `{ type, text }` snapshots. */\n  private snapshotBlocks(entry: PromptsManagerEntry): PromptDiffBlock[] {\n    return entry.contract.blocks.map(block => ({\n      type: block.type,\n      text: block.text,\n    }));\n  }\n\n  /**\n   * Resolve the body + declared-required keys for any `validate` target: a\n   * registered name (or `name@selector`), a `SystemPromptContract` instance, or\n   * a raw string.\n   */\n  private describeTarget(target: PromptValidateTarget): {\n    text: string;\n    required: readonly string[];\n  } {\n    if (typeof target === \"string\") {\n      // An inline `name@selector` (or a bare registered name) resolves through\n      // the registry; anything else is a raw prompt body validated verbatim.\n      const { baseName, selector } = this.parseSelector(target, undefined);\n      const entry = selector\n        ? this.resolveSelector(baseName, selector)\n        : this.latestEntry(baseName);\n\n      if (entry) {\n        return describeContractTarget(entry.contract);\n      }\n\n      return { text: target, required: [] };\n    }\n\n    if (isSystemPromptContract(target)) {\n      return describeContractTarget(target);\n    }\n\n    if (isBlock(target)) {\n      return { text: target.text, required: [] };\n    }\n\n    throw new InvalidRequestError(\n      \"validate() target must be a registered name, a SystemPromptContract, \" +\n        \"a prompt block, or a raw string.\",\n      { context: { target } },\n    );\n  }\n\n  /**\n   * The next integer version label for a name — `\"1\"` for the first, then the\n   * count of existing versions plus one. String-typed to match the free-form\n   * `version` label shape.\n   */\n  private nextVersion(name: string): string {\n    const count = [...this.entries.values()].filter(\n      entry => entry.name === name,\n    ).length;\n\n    return String(count + 1);\n  }\n\n  /** Pick the highest-`addedAt` entry for a name, or `undefined` when absent. */\n  private latestEntry(name: string): PromptsManagerEntry | undefined {\n    let latest: PromptsManagerEntry | undefined;\n\n    for (const entry of this.entries.values()) {\n      if (entry.name !== name) {\n        continue;\n      }\n\n      if (!latest || entry.addedAt > latest.addedAt) {\n        latest = entry;\n      }\n    }\n\n    return latest;\n  }\n\n  /**\n   * Split a name argument into its base name + optional selector. The selector\n   * comes from the explicit second argument when present, else from an inline\n   * `name@selector` in the first argument. A bare name yields no selector.\n   */\n  private parseSelector(\n    name: string,\n    versionOrTag: string | undefined,\n  ): { baseName: string; selector: string | undefined } {\n    if (versionOrTag !== undefined) {\n      return { baseName: name, selector: versionOrTag };\n    }\n\n    const at = name.indexOf(\"@\");\n\n    if (at > 0) {\n      return { baseName: name.slice(0, at), selector: name.slice(at + 1) };\n    }\n\n    return { baseName: name, selector: undefined };\n  }\n\n  /**\n   * Resolve a selector (a version label OR a pinned tag) to a concrete entry.\n   * Version labels win over tags when both could match — the explicit label is\n   * the more specific intent. Returns `undefined` when neither resolves.\n   */\n  private resolveSelector(\n    name: string,\n    selector: string,\n  ): PromptsManagerEntry | undefined {\n    const byVersion = this.entries.get(promptKey(name, selector));\n\n    if (byVersion) {\n      return byVersion;\n    }\n\n    const pinnedVersion = this.pins.get(name)?.get(selector);\n\n    if (pinnedVersion !== undefined) {\n      return this.entries.get(promptKey(name, pinnedVersion));\n    }\n\n    return undefined;\n  }\n\n  /**\n   * Resolve an entry by name (+ optional version / tag / inline selector),\n   * throwing {@link InvalidRequestError} when the name or the requested\n   * selector is unknown. The single lookup path `get` / `resolve` share.\n   */\n  private requireEntry(\n    name: string,\n    versionOrTag?: string,\n  ): PromptsManagerEntry {\n    const { baseName, selector } = this.parseSelector(name, versionOrTag);\n\n    if (selector !== undefined) {\n      const entry = this.resolveSelector(baseName, selector);\n\n      if (!entry) {\n        throw new InvalidRequestError(\n          `No prompt registered as \"${baseName}\" with version/tag \"${selector}\".`,\n          { context: { name: baseName, selector } },\n        );\n      }\n\n      return entry;\n    }\n\n    const latest = this.latestEntry(baseName);\n\n    if (!latest) {\n      throw new InvalidRequestError(\n        `No prompt registered under name \"${baseName}\".`,\n        { context: { name: baseName } },\n      );\n    }\n\n    return latest;\n  }\n\n  /**\n   * Resolve a name + EXACT version label to its entry (no tag fallback), for\n   * `diff` / `export` where a concrete version is always required. Throws\n   * {@link InvalidRequestError} on a miss.\n   */\n  private requireExact(name: string, version: string): PromptsManagerEntry {\n    const entry = this.entries.get(promptKey(name, version));\n\n    if (!entry) {\n      throw new InvalidRequestError(\n        `No prompt registered as \"${promptKey(name, version)}\".`,\n        { context: { name, version } },\n      );\n    }\n\n    return entry;\n  }\n}\n\n/**\n * Narrow an arbitrary value to a `SystemPromptContract` — true when it exposes\n * the builder surface (`blocks` array + a callable `resolve`) AND a callable\n * `meta`. Robust across duplicate package copies (no `instanceof`).\n */\nfunction isSystemPromptContract(\n  value: unknown,\n): value is SystemPromptContract {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    Array.isArray((value as { blocks?: unknown }).blocks) &&\n    typeof (value as { resolve?: unknown }).resolve === \"function\" &&\n    typeof (value as { meta?: unknown }).meta === \"function\"\n  );\n}\n\n/**\n * Narrow an arbitrary value to a single `SystemPromptBlockContract` — true when\n * it carries a string `type` + `text` and a callable `resolve` but is NOT a\n * full prompt (no `blocks` array). Lets `validate` accept a lone block.\n */\nfunction isBlock(value: unknown): value is SystemPromptBlockContract {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as { type?: unknown }).type === \"string\" &&\n    typeof (value as { text?: unknown }).text === \"string\" &&\n    typeof (value as { resolve?: unknown }).resolve === \"function\"\n  );\n}\n\n/**\n * Create a new, isolated prompts manager.\n *\n * **Role.** Public factory for {@link PromptsManagerContract} — keeps\n * user-facing code free of `new` and consistent with the other `ai.*`\n * factories. Each call returns a fresh registry, so parallel test suites and\n * multi-tenant apps never share mutable global prompt state.\n *\n * The process-wide instance that named `systemPrompt(...)` builders\n * auto-register into is `ai.prompts` (see {@link defaultPromptsManager}).\n *\n * @param options - Optional wiring, notably a `judgeCache` that memoizes\n *   LLM-judge verdicts (absent ⇒ every judge pass runs live).\n *\n * @example\n * const registry = prompts();\n * registry.register(systemPrompt(\"You are support.\", { name: \"support\" }));\n * registry.resolve(\"support\"); // \"You are support.\"\n *\n * @example\n * // Memoize judge verdicts across validations.\n * const registry = prompts({ judgeCache: new MemoryCacheDriver() });\n */\nexport function prompts(options?: PromptsManagerOptions): PromptsManagerContract {\n  return new PromptsManager(options);\n}\n\n/**\n * The process-wide default manager that named prompts auto-register into.\n *\n * Held as a module-level singleton (lazily created on first access) so\n * `system-prompt.ts` can register a named builder without importing the\n * `PromptsManager` class — keeping the auto-registration seam free of a\n * runtime import cycle.\n */\nlet defaultManager: PromptsManagerContract | undefined;\n\n/** Accessor for the process-wide default {@link PromptsManagerContract}. */\nexport function defaultPromptsManager(): PromptsManagerContract {\n  if (!defaultManager) {\n    defaultManager = new PromptsManager();\n  }\n\n  return defaultManager;\n}\n"],"mappings":"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"}

package/esm/prompts/prompts-manager.type.d.mts

@@ -0,0 +1,172 @@
+import { ModelContract } from "../contracts/model.contract.mjs";
+import { Placeholders } from "../contracts/placeholders.type.mjs";
+import { SystemPromptBlockContract } from "../contracts/system-prompt.contract.mjs";
+
+//#region ../@warlock.js/ai/src/prompts/prompts-manager.type.d.ts
+/**
+ * The minimal cache surface the judge-verdict memo needs — a structural subset
+ * of `@warlock.js/cache`'s `CacheDriver` (`get` / `set`). Typed structurally
+ * (not imported) so `@warlock.js/cache` stays a strictly OPTIONAL peer: a
+ * consumer that never validates with a judge never needs the cache package.
+ * Any `CacheDriver` instance satisfies this.
+ */
+interface PromptJudgeCacheLike {
+  /** Read a cached value, or `null` on a miss. */
+  get<T = unknown>(key: string): Promise<T | null>;
+  /** Write a value (TTL / options ignored by this memo path). */
+  set(key: string, value: unknown, ttlOrOptions?: unknown): Promise<unknown>;
+}
+/**
+ * Options for the `prompts(options?)` factory.
+ */
+interface PromptsManagerOptions {
+  /**
+   * Optional cache that memoizes LLM-judge verdicts. Keyed by a content hash of
+   * the resolved prompt body + the judge model's id, so a re-validation of the
+   * same prompt with the same judge skips the model call. Absent ⇒ every judge
+   * pass runs live (a pure no-op seam — `@warlock.js/cache` stays optional).
+   */
+  readonly judgeCache?: PromptJudgeCacheLike;
+}
+/**
+ * What {@link PromptsManagerContract.validate} accepts as its target:
+ * - a registered prompt **name** (resolved to its latest version, or a tagged /
+ *   `name@version` selector — same syntax `get` accepts);
+ * - a `SystemPromptContract` instance (named or anonymous);
+ * - a raw prompt **string** (validated verbatim, no registry lookup).
+ */
+type PromptValidateTarget = string | SystemPromptBlockContract | object;
+/**
+ * Options for {@link PromptsManagerContract.validate}.
+ */
+interface PromptsValidateOptions {
+  /**
+   * Placeholder values the caller intends to supply at resolve time. Any
+   * `{{key}}` present in these (or carrying an inline default, or declared in
+   * `meta.required`) is NOT reported as missing.
+   */
+  readonly placeholders?: Placeholders;
+  /**
+   * Extra placeholder keys to treat as known/declared (beyond the prompt's own
+   * `meta.required`). A key listed here is never reported missing.
+   */
+  readonly declare?: readonly string[];
+  /**
+   * Optional model that powers the LLM-as-judge quality pass. When omitted,
+   * `validate` runs the deterministic placeholder check only and returns no
+   * `score`. The judge is Nova-safe — it never throws and degrades to an
+   * `issues` note (leaving `score` undefined) on any failure.
+   */
+  readonly judge?: ModelContract;
+  /**
+   * Per-call judge-verdict cache override. When set, takes precedence over the
+   * manager's `judgeCache` for this call only. Same memo semantics: only used
+   * when `judge` is also supplied.
+   */
+  readonly judgeCache?: PromptJudgeCacheLike;
+}
+/**
+ * Unified result of {@link PromptsManagerContract.validate}.
+ *
+ * `ok` is the deterministic verdict alone — `true` iff no required placeholder
+ * is missing. The optional LLM-judge `score` / `issues` are advisory and never
+ * flip `ok`, so a flaky judge can't fail an otherwise-valid prompt.
+ */
+interface PromptValidationResult {
+  /** `true` when no required placeholder is missing (deterministic verdict). */
+  readonly ok: boolean;
+  /** Placeholder keys referenced with no default, unsupplied and undeclared. */
+  readonly missing: string[];
+  /**
+   * LLM-judge quality score in `[0, 1]`. Present only when a `judge` model was
+   * supplied AND the judge produced a usable verdict; `undefined` when no judge
+   * ran or the judge degraded.
+   */
+  readonly score?: number;
+  /**
+   * Advisory findings — the judge's reason(s) and/or a degrade note. Present
+   * (possibly empty) only when a `judge` model was supplied.
+   */
+  readonly issues?: string[];
+}
+/**
+ * One version in a bulk {@link PromptsManagerContract.define} call (or a
+ * `.templates([...])` builder call): a version label plus its body, given
+ * either as a raw string (wrapped into a single instruction block) or as an
+ * explicit ordered list of blocks (used verbatim).
+ */
+interface PromptTemplateVersion {
+  /** Version label, e.g. `"1"`, `"2"`, `"2025-draft"`. */
+  readonly version: string;
+  /**
+   * The version body. A string becomes one instruction block; an array of
+   * blocks is registered verbatim, preserving order.
+   */
+  readonly template: string | readonly SystemPromptBlockContract[];
+}
+/**
+ * One block in a {@link PromptDiff} — its discriminator and raw text, so a diff
+ * is comparable without resolving placeholders.
+ */
+interface PromptDiffBlock {
+  /** Block discriminator (`"persona"` / `"instruction"` / …). */
+  readonly type: string;
+  /** Raw template text. */
+  readonly text: string;
+}
+/**
+ * Block-level diff between two registered versions of a prompt, returned by
+ * {@link PromptsManagerContract.diff}. Blocks are matched positionally.
+ */
+interface PromptDiff {
+  /** The prompt name diffed. */
+  readonly name: string;
+  /** The left/from version label. */
+  readonly from: string;
+  /** The right/to version label. */
+  readonly to: string;
+  /** Blocks present in `to` but not at the same position in `from`. */
+  readonly added: PromptDiffBlock[];
+  /** Blocks present in `from` but not at the same position in `to`. */
+  readonly removed: PromptDiffBlock[];
+  /** Blocks at the same position whose `type` or `text` changed. */
+  readonly changed: {
+    from: PromptDiffBlock;
+    to: PromptDiffBlock;
+  }[];
+  /** `true` when the two versions have identical blocks in identical order. */
+  readonly identical: boolean;
+}
+/**
+ * The portable JSON shape of a single registered version, used by
+ * {@link PromptsManagerContract.export} / `import`. Blocks are flattened to
+ * `{ type, text }` so the registry round-trips without live builder instances.
+ */
+interface ExportedPromptVersion {
+  readonly version: string;
+  readonly blocks: PromptDiffBlock[];
+  /** Tags pinned to this exact version (via `tag(name, tag, version)`). */
+  readonly tags?: string[];
+  /** Carried-through `meta.description`, when present. */
+  readonly description?: string;
+  /** Carried-through `meta.required`, when present. */
+  readonly required?: string[];
+}
+/**
+ * The portable JSON shape of one registered name and all its versions, used by
+ * {@link PromptsManagerContract.export} / `import`.
+ */
+interface ExportedPrompt {
+  readonly name: string;
+  readonly versions: ExportedPromptVersion[];
+}
+/**
+ * The full portable registry snapshot returned by
+ * {@link PromptsManagerContract.export} and accepted by `import`.
+ */
+interface ExportedRegistry {
+  readonly prompts: ExportedPrompt[];
+}
+//#endregion
+export { ExportedPrompt, ExportedPromptVersion, ExportedRegistry, PromptDiff, PromptDiffBlock, PromptJudgeCacheLike, PromptTemplateVersion, PromptValidateTarget, PromptValidationResult, PromptsManagerOptions, PromptsValidateOptions };
+//# sourceMappingURL=prompts-manager.type.d.mts.map

package/esm/prompts/prompts-manager.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts-manager.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/prompts/prompts-manager.type.ts"],"mappings":";;;;;;;AAWA;;;;;UAAiB,oBAAA;EAIkD;EAFjE,GAAA,cAAiB,GAAA,WAAc,OAAA,CAAQ,CAAA;EAAvC;EAEA,GAAA,CAAI,GAAA,UAAa,KAAA,WAAgB,YAAA,aAAyB,OAAA;AAAA;;;;UAM3C,qBAAA;EANE;;;;AAAgD;AAMnE;EANmB,SAaR,UAAA,GAAa,oBAAoB;AAAA;;AAAA;AAU5C;;;;AAAqE;KAAzD,oBAAA,YAAgC,yBAAyB;;;;UAKpD,sBAAA;EA2BO;;;;;EAAA,SArBb,YAAA,GAAe,YAAA;EAcf;;;;EAAA,SARA,OAAA;EAeiC;AAU5C;;;;;EAV4C,SAPjC,KAAA,GAAQ,aAAA;EA6BR;;;AAMM;AASjB;EAfW,SAtBA,UAAA,GAAa,oBAAA;AAAA;;;;;;AA6CwC;AAOhE;UA1CiB,sBAAA;;WAEN,EAAA;EA4CI;EAAA,SAzCJ,OAAA;EAgDgB;;;;;EAAA,SAzChB,KAAA;EAqDqD;;;;EAAA,SA/CrD,MAAA;AAAA;;;;;;;UASM,qBAAA;EAsCgC;EAAA,SApCtC,OAAA;EAsCS;AAAA;AAQpB;;EARoB,SAhCT,QAAA,oBAA4B,yBAAyB;AAAA;;;;;UAO/C,eAAA;EAyCN;EAAA,SAvCA,IAAA;EAuCQ;EAAA,SArCR,IAAI;AAAA;;;;;UAOE,UAAA;EAuCyB;EAAA,SArC/B,IAAA;EA4CM;EAAA,SA1CN,IAAA;;WAEA,EAAA;EAyCuB;EAAA,SAvCvB,KAAA,EAAO,eAAA;;WAEP,OAAA,EAAS,eAAA;;WAET,OAAA;IAAW,IAAA,EAAM,eAAA;IAAiB,EAAA,EAAI,eAAA;EAAA;;WAEtC,SAAA;AAAA;;;;;;UAQM,qBAAA;EAAA,SACN,OAAA;EAAA,SACA,MAAA,EAAQ,eAAe;;WAEvB,IAAA;;WAEA,WAAA;;WAEA,QAAA;AAAA;;;;;UAOM,cAAA;EAAA,SACN,IAAA;EAAA,SACA,QAAA,EAAU,qBAAqB;AAAA;;;;;UAOzB,gBAAA;EAAA,SACN,OAAA,EAAS,cAAc;AAAA"}