@warlock.js/core 4.3.0 → 4.5.0

package/esm/ai/src/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/ai/src/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/ai/src/prompts/prompts-validate.mjs

@@ -0,0 +1,200 @@
+import { judge } from "../eval/judge-scorer.mjs";
+import { agent } from "../agent/agent.mjs";
+import { PROMPT_JUDGE_RUBRIC } from "../prompt/prompt-validate.mjs";
+
+//#region ../@warlock.js/ai/src/prompts/prompts-validate.ts
+/**
+* Placeholder matcher — kept in lock-step with the matcher
+* `renderPlaceholders` (`src/system-prompt/render-placeholders.ts`) and the
+* legacy `prompt-validate` lint both use, so the deterministic validator sees
+* the exact same `{{key}}` / `{{a.b}}` / `{{key|default}}` set the renderer
+* substitutes. Global so every occurrence is collected.
+*/
+const PLACEHOLDER_PATTERN = /\{\{\s*([^{}]+?)\s*\}\}/g;
+/**
+* Collect every distinct placeholder occurrence from a template, in first-seen
+* order. A key is considered to "have a default" only when EVERY occurrence of
+* it carries one — a single bare `{{key}}` means the renderer can leave it
+* unresolved, so the key is still required.
+*/
+function collectPlaceholders(template) {
+	const byPath = /* @__PURE__ */ new Map();
+	const order = [];
+	for (const match of template.matchAll(PLACEHOLDER_PATTERN)) {
+		const [rawPath, rawDefault] = match[1].split("|");
+		const path = rawPath.trim();
+		if (path.length === 0) continue;
+		const hasDefault = rawDefault !== void 0;
+		if (!byPath.has(path)) {
+			byPath.set(path, hasDefault);
+			order.push(path);
+		} else byPath.set(path, (byPath.get(path) ?? false) && hasDefault);
+	}
+	return order.map((path) => ({
+		path,
+		hasDefault: byPath.get(path) ?? false
+	}));
+}
+/**
+* Run the deterministic (model-free) half of validation over a resolved prompt
+* body. Reports every `{{key}}` placeholder that has NO inline default and is
+* neither supplied in `provided` nor declared in `declared` (the prompt's
+* `meta.required` plus any caller-declared keys).
+*
+* Pure and synchronous — the only required half of `validate`; the LLM-judge
+* half is optional and layered on top.
+*
+* @param text - The resolved prompt body (placeholders may still be present).
+* @param provided - Placeholder keys the caller has supplied a value for.
+* @param declared - Placeholder keys declared as known/required (e.g. `meta.required`).
+*/
+function findMissingPlaceholders(text, provided, declared) {
+	const missing = [];
+	for (const { path, hasDefault } of collectPlaceholders(text)) {
+		if (hasDefault) continue;
+		if (provided.has(path) || declared.has(path)) continue;
+		missing.push(path);
+	}
+	return missing;
+}
+/**
+* A `meta.required` key absent from the template entirely — declared as
+* required but never referenced — is itself a defect worth surfacing. Returns
+* the declared keys that appear nowhere in the body.
+*/
+function findUnreferencedRequired(text, required) {
+	const present = new Set(collectPlaceholders(text).map((p) => p.path));
+	return required.filter((key) => !present.has(key));
+}
+/**
+* Build the one-shot judge agent the optional LLM-as-judge pass runs. Mirrors
+* the legacy `prompt.ts` judge agent (strict-JSON instruction so the verdict
+* parses even without an output schema), so the two validate paths share one
+* judging contract.
+*/
+function buildJudgeAgent(model) {
+	return agent({
+		name: "prompt-quality-judge",
+		model,
+		systemPrompt: "You are a strict prompt-quality grader. Respond with JSON only: { \"score\": <0..1>, \"passed\": <true|false>, \"reason\": \"<short explanation>\" }."
+	});
+}
+/**
+* Run the optional LLM-as-judge pass over a resolved prompt body, REUSING the
+* eval `judge` scorer (the same path `prompt().validate` uses) so there is no
+* second judging implementation.
+*
+* **Nova-safe by contract.** The judge NEVER throws here: the eval scorer
+* already degrades a broken judge to `score: 0` with a failure reason, and any
+* exception that still escapes (model wiring, agent construction) is caught.
+* Both degrade paths surface `score: undefined` plus an issue note — so a flaky
+* judge can never fail an otherwise-valid prompt.
+*
+* @param text - The resolved prompt body under evaluation.
+* @param model - The model that powers the judge agent.
+*/
+async function judgePromptBody(text, model) {
+	try {
+		const verdict = await judge({
+			agent: buildJudgeAgent(model),
+			rubric: PROMPT_JUDGE_RUBRIC
+		})({
+			case: {
+				name: "prompt-quality",
+				input: "Grade the system prompt below."
+			},
+			text,
+			result: { text },
+			output: void 0
+		});
+		if (verdict.score === 0 && typeof verdict.reason === "string" && /^judge (failed|returned no parseable)/.test(verdict.reason)) return { issues: [`LLM-judge unavailable: ${verdict.reason}`] };
+		return {
+			score: verdict.score,
+			issues: verdict.reason ? [verdict.reason] : []
+		};
+	} catch (error) {
+		return { issues: [`LLM-judge unavailable: ${error instanceof Error ? error.message : String(error)}`] };
+	}
+}
+/**
+* Non-cryptographic 53-bit string hash (cyrb53) — deterministic across runs
+* and platforms, with no `node:crypto` dependency (keeps the validate path
+* usable in any runtime). Mirrors the VCR request hash; collision-resistant
+* enough for a per-prompt judge-verdict keyspace. Returned as base-36.
+*/
+function hashString(input) {
+	let h1 = 3735928559;
+	let h2 = 1103547991;
+	for (let i = 0; i < input.length; i++) {
+		const ch = input.charCodeAt(i);
+		h1 = Math.imul(h1 ^ ch, 2654435761);
+		h2 = Math.imul(h2 ^ ch, 1597334677);
+	}
+	h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507);
+	h1 ^= Math.imul(h2 ^ h2 >>> 13, 3266489909);
+	h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507);
+	h2 ^= Math.imul(h1 ^ h1 >>> 13, 3266489909);
+	return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36);
+}
+/**
+* Build the judge-verdict cache key for a resolved prompt body + judge model.
+* Combines the model's `provider:name` identity with a content hash of the
+* body, so the same prompt graded by the same judge hits the cache, while any
+* change to either misses it.
+*/
+function judgeCacheKey(text, model) {
+	return `prompts.judge.${model.provider}:${model.name}.${hashString(text)}`;
+}
+/**
+* Run the judge pass with an OPTIONAL memo cache in front. On a hit, the stored
+* {@link JudgeOutcome} is returned without a model call; on a miss, the live
+* judge runs and a USABLE verdict (one carrying a `score`) is written back.
+* Degraded outcomes (no score) are NOT cached — a transient judge failure must
+* never poison the memo. A `null`/absent cache degrades to a direct judge call.
+*
+* Cache I/O is itself fault-tolerant: a `get`/`set` that rejects is swallowed
+* so a flaky cache can never break (or fail) validation.
+*
+* @param text - The resolved prompt body under evaluation.
+* @param model - The judge model.
+* @param cache - Optional verdict memo (any `CacheDriver`-like get/set surface).
+*/
+async function judgePromptBodyCached(text, model, cache) {
+	if (!cache) return judgePromptBody(text, model);
+	const key = judgeCacheKey(text, model);
+	const cached = await readJudgeCache(cache, key);
+	if (cached) return cached;
+	const outcome = await judgePromptBody(text, model);
+	if (outcome.score !== void 0) await writeJudgeCache(cache, key, outcome);
+	return outcome;
+}
+/** Read a cached verdict, swallowing any cache fault (treated as a miss). */
+async function readJudgeCache(cache, key) {
+	try {
+		return await cache.get(key) ?? void 0;
+	} catch {
+		return;
+	}
+}
+/** Write a verdict, swallowing any cache fault (best-effort memo). */
+async function writeJudgeCache(cache, key, outcome) {
+	try {
+		await cache.set(key, outcome);
+	} catch {}
+}
+/**
+* Resolve the body + declared-required keys for a validation target that is a
+* `SystemPromptContract` (named or anonymous). The declared set is the
+* prompt's `meta.required` (when present).
+*/
+function describeContractTarget(contract) {
+	const meta = contract.meta();
+	return {
+		text: contract.resolve(),
+		required: meta?.required ?? []
+	};
+}
+
+//#endregion
+export { describeContractTarget, findMissingPlaceholders, findUnreferencedRequired, judgePromptBodyCached };
+//# sourceMappingURL=prompts-validate.mjs.map