@warlock.js/ai 4.2.10 → 4.3.0

package/esm/memory/memory.mjs

@@ -0,0 +1,166 @@
+import { resolveDefaultStore } from "../config.mjs";
+import { EpisodicMemory } from "./episodic-memory.mjs";
+import { ProceduralMemory } from "./procedural-memory.mjs";
+import { SemanticMemory } from "./semantic-memory.mjs";
+import { WorkingMemory } from "./working-memory.mjs";
+
+//#region ../@warlock.js/ai/src/memory/memory.ts
+const DEFAULT_NAME = "memory";
+const DEFAULT_SEMANTIC_NAMESPACE = "ai.memory.semantic";
+const DEFAULT_EPISODIC_NAMESPACE = "ai.memory.episodic";
+const DEFAULT_PROCEDURAL_NAMESPACE = "ai.memory.procedural";
+const DEFAULT_K = 5;
+const DEFAULT_THRESHOLD = .7;
+const DEFAULT_RECENCY_WEIGHT = .3;
+const DEFAULT_HALF_LIFE_MS = 10080 * 60 * 1e3;
+const DEFAULT_REINFORCEMENT_WEIGHT = .3;
+/**
+* Create an agent memory store (memory core M2).
+*
+* Wires up to four tiers behind the {@link MemoryContract}: **working**
+* (in-run scratch, recency), **semantic** (durable facts by cosine
+* similarity), **episodic** (durable events, similarity blended with
+* recency), and **procedural** (durable how-tos, similarity blended with
+* reinforcement). The working tier is on by default; the other three each
+* activate only when their config is supplied. The three vector tiers
+* mirror how `semanticCache` delegates similarity to the cache driver's
+* `.similar()`.
+*
+* Resolution happens once here, at construction (loud), rather than per
+* call (silent until first use): a vector-tier config with no `store` and
+* no `ai.config({ defaultStore })` throws now; enabling no tier at all
+* throws now.
+*
+* Decay / forgetting (TTL-based falloff, eviction) remains deferred.
+*
+* @example
+* import { ai } from "@warlock.js/ai";
+* import { MemoryCacheDriver } from "@warlock.js/cache";
+*
+* const store = new MemoryCacheDriver();
+* store.setOptions({});
+*
+* const mem = ai.memory({
+*   semantic: { embedder, store },
+*   defaultTier: "semantic",
+* });
+*
+* await mem.remember({ text: "User prefers concise answers." });
+* const hits = await mem.recall("how should I respond?", { k: 3 });
+*/
+function memory(config = {}) {
+	const name = config.name ?? DEFAULT_NAME;
+	const workingEnabled = config.working ?? true;
+	const defaultK = config.k ?? DEFAULT_K;
+	const defaultThreshold = config.threshold ?? DEFAULT_THRESHOLD;
+	const working = workingEnabled ? new WorkingMemory() : void 0;
+	const semantic = config.semantic ? buildSemanticTier(config.semantic, name) : void 0;
+	const episodic = config.episodic ? buildEpisodicTier(config.episodic, name) : void 0;
+	const procedural = config.procedural ? buildProceduralTier(config.procedural, name) : void 0;
+	const tiers = {
+		working,
+		semantic,
+		episodic,
+		procedural
+	};
+	if (!working && !semantic && !episodic && !procedural) throw new Error(`memory("${name}"): no tier enabled — enable \`working\` (default) or pass a \`semantic\` / \`episodic\` / \`procedural\` config; a memory with no tiers can neither store nor recall`);
+	const defaultTier = config.defaultTier ?? "working";
+	assertTierEnabled(defaultTier, tiers, name);
+	return {
+		name,
+		async remember(items) {
+			const list = Array.isArray(items) ? items : [items];
+			const writes = [];
+			for (const item of list) {
+				const tier = item.tier ?? defaultTier;
+				assertTierEnabled(tier, tiers, name);
+				if (tier === "working") {
+					working.remember(item);
+					continue;
+				}
+				if (tier === "semantic") {
+					writes.push(semantic.remember(item));
+					continue;
+				}
+				if (tier === "episodic") {
+					writes.push(episodic.remember(item));
+					continue;
+				}
+				writes.push(procedural.remember(item));
+			}
+			await Promise.all(writes);
+		},
+		async recall(query, options = {}) {
+			const k = options.k ?? defaultK;
+			const threshold = options.threshold ?? defaultThreshold;
+			if (options.tier) assertTierEnabled(options.tier, tiers, name);
+			const wants = (tier) => !options.tier || options.tier === tier;
+			const [workingHits, semanticHits, episodicHits, proceduralHits] = await Promise.all([
+				working && wants("working") ? Promise.resolve(working.recall(k)) : Promise.resolve([]),
+				semantic && wants("semantic") ? semantic.recall(query, k, threshold) : Promise.resolve([]),
+				episodic && wants("episodic") ? episodic.recall(query, k, threshold) : Promise.resolve([]),
+				procedural && wants("procedural") ? procedural.recall(query, k, threshold) : Promise.resolve([])
+			]);
+			return [
+				...workingHits,
+				...semanticHits,
+				...episodicHits,
+				...proceduralHits
+			].sort((first, second) => second.score - first.score).slice(0, k);
+		},
+		async clear(tier) {
+			const clears = [];
+			if (working && (!tier || tier === "working")) working.clear();
+			if (semantic && (!tier || tier === "semantic")) clears.push(semantic.clear());
+			if (episodic && (!tier || tier === "episodic")) clears.push(episodic.clear());
+			if (procedural && (!tier || tier === "procedural")) clears.push(procedural.clear());
+			await Promise.all(clears);
+		}
+	};
+}
+/**
+* Resolve the semantic tier's store (explicit `store` wins, else the
+* global `ai.config({ defaultStore })`) and build the tier. Throws at
+* construction when neither is available — the same loud-now contract
+* `semanticCache` follows.
+*/
+function buildSemanticTier(semanticConfig, name) {
+	const store = semanticConfig.store ?? resolveDefaultStore();
+	if (!store) throw new Error(`memory("${name}"): semantic tier has no store — pass \`semantic.store\` or call \`ai.config({ defaultStore })\` at app boot before constructing the memory`);
+	return new SemanticMemory(semanticConfig.embedder, store, semanticConfig.namespace ?? DEFAULT_SEMANTIC_NAMESPACE);
+}
+/**
+* Resolve the episodic tier's store (explicit `store` wins, else the
+* global default) and build the tier with its recency knobs. Throws at
+* construction when neither store is available — the same loud-now
+* contract the semantic tier follows.
+*/
+function buildEpisodicTier(episodicConfig, name) {
+	const store = episodicConfig.store ?? resolveDefaultStore();
+	if (!store) throw new Error(`memory("${name}"): episodic tier has no store — pass \`episodic.store\` or call \`ai.config({ defaultStore })\` at app boot before constructing the memory`);
+	return new EpisodicMemory(episodicConfig.embedder, store, episodicConfig.namespace ?? DEFAULT_EPISODIC_NAMESPACE, episodicConfig.recencyWeight ?? DEFAULT_RECENCY_WEIGHT, episodicConfig.halfLifeMs ?? DEFAULT_HALF_LIFE_MS, episodicConfig.now ?? (() => Date.now()));
+}
+/**
+* Resolve the procedural tier's store and build the tier with its
+* reinforcement knob. Throws at construction when no store is available.
+*/
+function buildProceduralTier(proceduralConfig, name) {
+	const store = proceduralConfig.store ?? resolveDefaultStore();
+	if (!store) throw new Error(`memory("${name}"): procedural tier has no store — pass \`procedural.store\` or call \`ai.config({ defaultStore })\` at app boot before constructing the memory`);
+	return new ProceduralMemory(proceduralConfig.embedder, store, proceduralConfig.namespace ?? DEFAULT_PROCEDURAL_NAMESPACE, proceduralConfig.reinforcementWeight ?? DEFAULT_REINFORCEMENT_WEIGHT);
+}
+/**
+* Guard that a tier referenced by config / a call is actually enabled,
+* failing fast with an actionable message instead of a downstream
+* `undefined` dereference.
+*/
+function assertTierEnabled(tier, tiers, name) {
+	if (tier === "working" && !tiers.working) throw new Error(`memory("${name}"): working tier is disabled — set \`working: true\` (the default) to use it`);
+	if (tier === "semantic" && !tiers.semantic) throw new Error(`memory("${name}"): semantic tier is not configured — pass \`semantic\` config to use it`);
+	if (tier === "episodic" && !tiers.episodic) throw new Error(`memory("${name}"): episodic tier is not configured — pass \`episodic\` config to use it`);
+	if (tier === "procedural" && !tiers.procedural) throw new Error(`memory("${name}"): procedural tier is not configured — pass \`procedural\` config to use it`);
+}
+
+//#endregion
+export { memory };
+//# sourceMappingURL=memory.mjs.map

package/esm/memory/memory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/memory.ts"],"sourcesContent":["import { resolveDefaultStore } from \"../config\";\nimport type { MemoryConfig } from \"../contracts/memory/memory-config.type\";\nimport type {\n  MemoryItem,\n  MemoryTier,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport type { MemoryContract } from \"../contracts/memory/memory.contract\";\nimport type { RecallOptions } from \"../contracts/memory/recall-options.type\";\nimport { EpisodicMemory } from \"./episodic-memory\";\nimport { ProceduralMemory } from \"./procedural-memory\";\nimport { SemanticMemory } from \"./semantic-memory\";\nimport { WorkingMemory } from \"./working-memory\";\n\nconst DEFAULT_NAME = \"memory\";\nconst DEFAULT_SEMANTIC_NAMESPACE = \"ai.memory.semantic\";\nconst DEFAULT_EPISODIC_NAMESPACE = \"ai.memory.episodic\";\nconst DEFAULT_PROCEDURAL_NAMESPACE = \"ai.memory.procedural\";\nconst DEFAULT_K = 5;\nconst DEFAULT_THRESHOLD = 0.7;\nconst DEFAULT_RECENCY_WEIGHT = 0.3;\nconst DEFAULT_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000;\nconst DEFAULT_REINFORCEMENT_WEIGHT = 0.3;\n\n/**\n * Create an agent memory store (memory core M2).\n *\n * Wires up to four tiers behind the {@link MemoryContract}: **working**\n * (in-run scratch, recency), **semantic** (durable facts by cosine\n * similarity), **episodic** (durable events, similarity blended with\n * recency), and **procedural** (durable how-tos, similarity blended with\n * reinforcement). The working tier is on by default; the other three each\n * activate only when their config is supplied. The three vector tiers\n * mirror how `semanticCache` delegates similarity to the cache driver's\n * `.similar()`.\n *\n * Resolution happens once here, at construction (loud), rather than per\n * call (silent until first use): a vector-tier config with no `store` and\n * no `ai.config({ defaultStore })` throws now; enabling no tier at all\n * throws now.\n *\n * Decay / forgetting (TTL-based falloff, eviction) remains deferred.\n *\n * @example\n * import { ai } from \"@warlock.js/ai\";\n * import { MemoryCacheDriver } from \"@warlock.js/cache\";\n *\n * const store = new MemoryCacheDriver();\n * store.setOptions({});\n *\n * const mem = ai.memory({\n *   semantic: { embedder, store },\n *   defaultTier: \"semantic\",\n * });\n *\n * await mem.remember({ text: \"User prefers concise answers.\" });\n * const hits = await mem.recall(\"how should I respond?\", { k: 3 });\n */\nexport function memory(config: MemoryConfig = {}): MemoryContract {\n  const name = config.name ?? DEFAULT_NAME;\n  const workingEnabled = config.working ?? true;\n  const defaultK = config.k ?? DEFAULT_K;\n  const defaultThreshold = config.threshold ?? DEFAULT_THRESHOLD;\n\n  const working = workingEnabled ? new WorkingMemory() : undefined;\n\n  const semantic = config.semantic\n    ? buildSemanticTier(config.semantic, name)\n    : undefined;\n\n  const episodic = config.episodic\n    ? buildEpisodicTier(config.episodic, name)\n    : undefined;\n\n  const procedural = config.procedural\n    ? buildProceduralTier(config.procedural, name)\n    : undefined;\n\n  const tiers: Tiers = { working, semantic, episodic, procedural };\n\n  if (!working && !semantic && !episodic && !procedural) {\n    throw new Error(\n      `memory(\"${name}\"): no tier enabled — enable \\`working\\` (default) or pass a \\`semantic\\` / \\`episodic\\` / \\`procedural\\` config; a memory with no tiers can neither store nor recall`,\n    );\n  }\n\n  const defaultTier: MemoryTier = config.defaultTier ?? \"working\";\n\n  assertTierEnabled(defaultTier, tiers, name);\n\n  return {\n    name,\n    async remember(items: MemoryItem | MemoryItem[]): Promise<void> {\n      const list = Array.isArray(items) ? items : [items];\n\n      const writes: Promise<void>[] = [];\n\n      for (const item of list) {\n        const tier = item.tier ?? defaultTier;\n\n        assertTierEnabled(tier, tiers, name);\n\n        if (tier === \"working\") {\n          working!.remember(item);\n\n          continue;\n        }\n\n        if (tier === \"semantic\") {\n          writes.push(semantic!.remember(item));\n\n          continue;\n        }\n\n        if (tier === \"episodic\") {\n          writes.push(episodic!.remember(item));\n\n          continue;\n        }\n\n        writes.push(procedural!.remember(item));\n      }\n\n      await Promise.all(writes);\n    },\n    async recall(\n      query: string,\n      options: RecallOptions = {},\n    ): Promise<RecalledMemory[]> {\n      const k = options.k ?? defaultK;\n      const threshold = options.threshold ?? defaultThreshold;\n\n      if (options.tier) {\n        assertTierEnabled(options.tier, tiers, name);\n      }\n\n      const wants = (tier: MemoryTier): boolean =>\n        !options.tier || options.tier === tier;\n\n      const [workingHits, semanticHits, episodicHits, proceduralHits] =\n        await Promise.all([\n          working && wants(\"working\")\n            ? Promise.resolve(working.recall(k))\n            : Promise.resolve([] as RecalledMemory[]),\n          semantic && wants(\"semantic\")\n            ? semantic.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n          episodic && wants(\"episodic\")\n            ? episodic.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n          procedural && wants(\"procedural\")\n            ? procedural.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n        ]);\n\n      return [\n        ...workingHits,\n        ...semanticHits,\n        ...episodicHits,\n        ...proceduralHits,\n      ]\n        .sort((first, second) => second.score - first.score)\n        .slice(0, k);\n    },\n    async clear(tier?: MemoryTier): Promise<void> {\n      const clears: Promise<void>[] = [];\n\n      if (working && (!tier || tier === \"working\")) {\n        working.clear();\n      }\n\n      if (semantic && (!tier || tier === \"semantic\")) {\n        clears.push(semantic.clear());\n      }\n\n      if (episodic && (!tier || tier === \"episodic\")) {\n        clears.push(episodic.clear());\n      }\n\n      if (procedural && (!tier || tier === \"procedural\")) {\n        clears.push(procedural.clear());\n      }\n\n      await Promise.all(clears);\n    },\n  };\n}\n\n/** The four tier instances a `memory()` composes; `undefined` when off. */\ntype Tiers = {\n  working: WorkingMemory | undefined;\n  semantic: SemanticMemory | undefined;\n  episodic: EpisodicMemory | undefined;\n  procedural: ProceduralMemory | undefined;\n};\n\n/**\n * Resolve the semantic tier's store (explicit `store` wins, else the\n * global `ai.config({ defaultStore })`) and build the tier. Throws at\n * construction when neither is available — the same loud-now contract\n * `semanticCache` follows.\n */\nfunction buildSemanticTier(\n  semanticConfig: NonNullable<MemoryConfig[\"semantic\"]>,\n  name: string,\n): SemanticMemory {\n  const store = semanticConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): semantic tier has no store — pass \\`semantic.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new SemanticMemory(\n    semanticConfig.embedder,\n    store,\n    semanticConfig.namespace ?? DEFAULT_SEMANTIC_NAMESPACE,\n  );\n}\n\n/**\n * Resolve the episodic tier's store (explicit `store` wins, else the\n * global default) and build the tier with its recency knobs. Throws at\n * construction when neither store is available — the same loud-now\n * contract the semantic tier follows.\n */\nfunction buildEpisodicTier(\n  episodicConfig: NonNullable<MemoryConfig[\"episodic\"]>,\n  name: string,\n): EpisodicMemory {\n  const store = episodicConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): episodic tier has no store — pass \\`episodic.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new EpisodicMemory(\n    episodicConfig.embedder,\n    store,\n    episodicConfig.namespace ?? DEFAULT_EPISODIC_NAMESPACE,\n    episodicConfig.recencyWeight ?? DEFAULT_RECENCY_WEIGHT,\n    episodicConfig.halfLifeMs ?? DEFAULT_HALF_LIFE_MS,\n    episodicConfig.now ?? (() => Date.now()),\n  );\n}\n\n/**\n * Resolve the procedural tier's store and build the tier with its\n * reinforcement knob. Throws at construction when no store is available.\n */\nfunction buildProceduralTier(\n  proceduralConfig: NonNullable<MemoryConfig[\"procedural\"]>,\n  name: string,\n): ProceduralMemory {\n  const store = proceduralConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): procedural tier has no store — pass \\`procedural.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new ProceduralMemory(\n    proceduralConfig.embedder,\n    store,\n    proceduralConfig.namespace ?? DEFAULT_PROCEDURAL_NAMESPACE,\n    proceduralConfig.reinforcementWeight ?? DEFAULT_REINFORCEMENT_WEIGHT,\n  );\n}\n\n/**\n * Guard that a tier referenced by config / a call is actually enabled,\n * failing fast with an actionable message instead of a downstream\n * `undefined` dereference.\n */\nfunction assertTierEnabled(tier: MemoryTier, tiers: Tiers, name: string): void {\n  if (tier === \"working\" && !tiers.working) {\n    throw new Error(\n      `memory(\"${name}\"): working tier is disabled — set \\`working: true\\` (the default) to use it`,\n    );\n  }\n\n  if (tier === \"semantic\" && !tiers.semantic) {\n    throw new Error(\n      `memory(\"${name}\"): semantic tier is not configured — pass \\`semantic\\` config to use it`,\n    );\n  }\n\n  if (tier === \"episodic\" && !tiers.episodic) {\n    throw new Error(\n      `memory(\"${name}\"): episodic tier is not configured — pass \\`episodic\\` config to use it`,\n    );\n  }\n\n  if (tier === \"procedural\" && !tiers.procedural) {\n    throw new Error(\n      `memory(\"${name}\"): procedural tier is not configured — pass \\`procedural\\` config to use it`,\n    );\n  }\n}\n"],"mappings":"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"}

package/esm/memory/procedural-memory.mjs

@@ -0,0 +1,103 @@
+import { deriveMemoryId } from "./derive-id.mjs";
+
+//#region ../@warlock.js/ai/src/memory/procedural-memory.ts
+/**
+* Extra candidates pulled from `similar()` before re-ranking by the
+* reinforcement-blended score and slicing to `k` — reinforcement can
+* promote a well-worn procedure past a slightly-closer one-off, which the
+* raw top-`k` by similarity would miss.
+*/
+const RECALL_OVERSCAN = 5;
+/**
+* Procedural recall tier (memory core M2).
+*
+* Holds durable *how-to* knowledge — learned procedures, policies, and
+* playbooks — and retrieves the ones relevant to a query, **blended with
+* reinforcement** so procedures that have proven themselves (remembered /
+* re-affirmed more often) outrank one-offs at equal similarity. That
+* reinforcement weighting is the difference from the semantic tier (which
+* treats every fact equally): procedural memory gets *stronger with use*.
+*
+* Reinforcement is explicit and side-effect-free on read: re-remembering
+* a procedure (same id, or same text → same derived id) increments its
+* `uses`, so a caller strengthens a procedure by remembering it again
+* after a successful application. Recall never mutates.
+*
+* Like the other vector tiers it delegates similarity to the
+* `@warlock.js/cache` driver's `similar()`. The blended `score` stays in
+* `[0, 1]` so procedural hits merge and sort alongside the other tiers.
+*
+* Internal to the `memory()` factory — never exported on the package
+* surface.
+*/
+var ProceduralMemory = class {
+	constructor(embedder, store, namespace, reinforcementWeight) {
+		this.embedder = embedder;
+		this.store = store;
+		this.namespace = namespace;
+		this.reinforcementWeight = reinforcementWeight;
+	}
+	/**
+	* Embed the procedure text and index it, incrementing its `uses` when
+	* it already exists (reinforcement) or seeding it at `1` when new.
+	* Metadata on a reinforcing write wins; an omitted metadata keeps the
+	* prior value rather than wiping it.
+	*/
+	async remember(item) {
+		const id = item.id ?? deriveMemoryId(item.text);
+		const { vector } = await this.embedder.embed(item.text);
+		const existing = await this.store.get(this.keyFor(id));
+		const uses = (existing?.uses ?? 0) + 1;
+		const value = {
+			id,
+			text: item.text,
+			uses,
+			metadata: item.metadata ?? existing?.metadata
+		};
+		await this.store.set(this.keyFor(id), value, { vector });
+	}
+	/**
+	* Embed `query`, pull the nearest procedures clearing the similarity
+	* `threshold`, then re-rank each by a reinforcement-blended score and
+	* return the top `k`. The similarity floor still gates relevance;
+	* reinforcement only reorders procedures that already cleared it.
+	*/
+	async recall(query, k, threshold) {
+		const { vector } = await this.embedder.embed(query);
+		const hits = await this.store.similar(vector, {
+			topK: Math.max(k * RECALL_OVERSCAN, k),
+			threshold
+		});
+		const prefix = `${this.namespace}.`;
+		return hits.filter((hit) => hit.key.startsWith(prefix)).map((hit) => ({
+			id: hit.value.id,
+			text: hit.value.text,
+			tier: "procedural",
+			score: this.blend(hit.score, hit.value.uses),
+			metadata: hit.value.metadata
+		})).sort((first, second) => second.score - first.score).slice(0, k);
+	}
+	/** Drop every procedure written under this instance's namespace. */
+	async clear() {
+		await this.store.removeNamespace(this.namespace);
+	}
+	/**
+	* Combine raw similarity with a saturating reinforcement proxy:
+	* `(1 - w)·similarity + w·(uses / (uses + 1))`. A first-time procedure
+	* contributes `0.5`; each reinforcement nudges it toward `1` with
+	* diminishing returns. With `reinforcementWeight` 0 the score is pure
+	* similarity.
+	*/
+	blend(similarity, uses) {
+		const reinforcement = uses / (uses + 1);
+		return (1 - this.reinforcementWeight) * similarity + this.reinforcementWeight * reinforcement;
+	}
+	/** Namespaced key for an entry — dot separator, matching `similar()` keys. */
+	keyFor(id) {
+		return `${this.namespace}.${id}`;
+	}
+};
+
+//#endregion
+export { ProceduralMemory };
+//# sourceMappingURL=procedural-memory.mjs.map

package/esm/memory/procedural-memory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"procedural-memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/procedural-memory.ts"],"sourcesContent":["import type { CacheDriver, CacheSimilarHit } from \"@warlock.js/cache\";\nimport type { EmbedderContract } from \"../contracts/embedder.contract\";\nimport type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport { deriveMemoryId } from \"./derive-id\";\n\n/**\n * Shape persisted per procedure. `uses` is the reinforcement counter —\n * how many times the procedure has been remembered/re-affirmed — and\n * feeds the reinforcement half of the blended recall score. The vector\n * lives in the driver's index, so it is not duplicated here.\n */\ntype StoredProcedure = {\n  id: string;\n  text: string;\n  uses: number;\n  metadata?: Record<string, unknown>;\n};\n\n/**\n * Extra candidates pulled from `similar()` before re-ranking by the\n * reinforcement-blended score and slicing to `k` — reinforcement can\n * promote a well-worn procedure past a slightly-closer one-off, which the\n * raw top-`k` by similarity would miss.\n */\nconst RECALL_OVERSCAN = 5;\n\n/**\n * Procedural recall tier (memory core M2).\n *\n * Holds durable *how-to* knowledge — learned procedures, policies, and\n * playbooks — and retrieves the ones relevant to a query, **blended with\n * reinforcement** so procedures that have proven themselves (remembered /\n * re-affirmed more often) outrank one-offs at equal similarity. That\n * reinforcement weighting is the difference from the semantic tier (which\n * treats every fact equally): procedural memory gets *stronger with use*.\n *\n * Reinforcement is explicit and side-effect-free on read: re-remembering\n * a procedure (same id, or same text → same derived id) increments its\n * `uses`, so a caller strengthens a procedure by remembering it again\n * after a successful application. Recall never mutates.\n *\n * Like the other vector tiers it delegates similarity to the\n * `@warlock.js/cache` driver's `similar()`. The blended `score` stays in\n * `[0, 1]` so procedural hits merge and sort alongside the other tiers.\n *\n * Internal to the `memory()` factory — never exported on the package\n * surface.\n */\nexport class ProceduralMemory {\n  public constructor(\n    private readonly embedder: EmbedderContract,\n    private readonly store: CacheDriver<any, any>,\n    private readonly namespace: string,\n    private readonly reinforcementWeight: number,\n  ) {}\n\n  /**\n   * Embed the procedure text and index it, incrementing its `uses` when\n   * it already exists (reinforcement) or seeding it at `1` when new.\n   * Metadata on a reinforcing write wins; an omitted metadata keeps the\n   * prior value rather than wiping it.\n   */\n  public async remember(item: MemoryItem): Promise<void> {\n    const id = item.id ?? deriveMemoryId(item.text);\n    const { vector } = await this.embedder.embed(item.text);\n\n    const existing = await this.store.get<StoredProcedure>(this.keyFor(id));\n    const uses = (existing?.uses ?? 0) + 1;\n\n    const value: StoredProcedure = {\n      id,\n      text: item.text,\n      uses,\n      metadata: item.metadata ?? existing?.metadata,\n    };\n\n    await this.store.set(this.keyFor(id), value, { vector });\n  }\n\n  /**\n   * Embed `query`, pull the nearest procedures clearing the similarity\n   * `threshold`, then re-rank each by a reinforcement-blended score and\n   * return the top `k`. The similarity floor still gates relevance;\n   * reinforcement only reorders procedures that already cleared it.\n   */\n  public async recall(\n    query: string,\n    k: number,\n    threshold: number,\n  ): Promise<RecalledMemory[]> {\n    const { vector } = await this.embedder.embed(query);\n\n    const hits = await this.store.similar<StoredProcedure>(vector, {\n      topK: Math.max(k * RECALL_OVERSCAN, k),\n      threshold,\n    });\n\n    const prefix = `${this.namespace}.`;\n\n    return hits\n      .filter((hit: CacheSimilarHit<StoredProcedure>) =>\n        hit.key.startsWith(prefix),\n      )\n      .map((hit: CacheSimilarHit<StoredProcedure>) => ({\n        id: hit.value.id,\n        text: hit.value.text,\n        tier: \"procedural\" as const,\n        score: this.blend(hit.score, hit.value.uses),\n        metadata: hit.value.metadata,\n      }))\n      .sort((first, second) => second.score - first.score)\n      .slice(0, k);\n  }\n\n  /** Drop every procedure written under this instance's namespace. */\n  public async clear(): Promise<void> {\n    await this.store.removeNamespace(this.namespace);\n  }\n\n  /**\n   * Combine raw similarity with a saturating reinforcement proxy:\n   * `(1 - w)·similarity + w·(uses / (uses + 1))`. A first-time procedure\n   * contributes `0.5`; each reinforcement nudges it toward `1` with\n   * diminishing returns. With `reinforcementWeight` 0 the score is pure\n   * similarity.\n   */\n  private blend(similarity: number, uses: number): number {\n    const reinforcement = uses / (uses + 1);\n\n    return (\n      (1 - this.reinforcementWeight) * similarity +\n      this.reinforcementWeight * reinforcement\n    );\n  }\n\n  /** Namespaced key for an entry — dot separator, matching `similar()` keys. */\n  private keyFor(id: string): string {\n    return `${this.namespace}.${id}`;\n  }\n}\n"],"mappings":";;;;;;;;;AA2BA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;AAwBxB,IAAa,mBAAb,MAA8B;CAC5B,AAAO,YACL,AAAiB,UACjB,AAAiB,OACjB,AAAiB,WACjB,AAAiB,qBACjB;EAJiB;EACA;EACA;EACA;CAChB;;;;;;;CAQH,MAAa,SAAS,MAAiC;EACrD,MAAM,KAAK,KAAK,MAAM,eAAe,KAAK,IAAI;EAC9C,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,IAAI;EAEtD,MAAM,WAAW,MAAM,KAAK,MAAM,IAAqB,KAAK,OAAO,EAAE,CAAC;EACtE,MAAM,QAAQ,UAAU,QAAQ,KAAK;EAErC,MAAM,QAAyB;GAC7B;GACA,MAAM,KAAK;GACX;GACA,UAAU,KAAK,YAAY,UAAU;EACvC;EAEA,MAAM,KAAK,MAAM,IAAI,KAAK,OAAO,EAAE,GAAG,OAAO,EAAE,OAAO,CAAC;CACzD;;;;;;;CAQA,MAAa,OACX,OACA,GACA,WAC2B;EAC3B,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK;EAElD,MAAM,OAAO,MAAM,KAAK,MAAM,QAAyB,QAAQ;GAC7D,MAAM,KAAK,IAAI,IAAI,iBAAiB,CAAC;GACrC;EACF,CAAC;EAED,MAAM,SAAS,GAAG,KAAK,UAAU;EAEjC,OAAO,KACJ,QAAQ,QACP,IAAI,IAAI,WAAW,MAAM,CAC3B,CAAC,CACA,KAAK,SAA2C;GAC/C,IAAI,IAAI,MAAM;GACd,MAAM,IAAI,MAAM;GAChB,MAAM;GACN,OAAO,KAAK,MAAM,IAAI,OAAO,IAAI,MAAM,IAAI;GAC3C,UAAU,IAAI,MAAM;EACtB,EAAE,CAAC,CACF,MAAM,OAAO,WAAW,OAAO,QAAQ,MAAM,KAAK,CAAC,CACnD,MAAM,GAAG,CAAC;CACf;;CAGA,MAAa,QAAuB;EAClC,MAAM,KAAK,MAAM,gBAAgB,KAAK,SAAS;CACjD;;;;;;;;CASA,AAAQ,MAAM,YAAoB,MAAsB;EACtD,MAAM,gBAAgB,QAAQ,OAAO;EAErC,QACG,IAAI,KAAK,uBAAuB,aACjC,KAAK,sBAAsB;CAE/B;;CAGA,AAAQ,OAAO,IAAoB;EACjC,OAAO,GAAG,KAAK,UAAU,GAAG;CAC9B;AACF"}

package/esm/memory/semantic-memory.mjs

@@ -0,0 +1,80 @@
+import { deriveMemoryId } from "./derive-id.mjs";
+
+//#region ../@warlock.js/ai/src/memory/semantic-memory.ts
+/**
+* Semantic recall tier (memory core M1).
+*
+* Owns: embedding remembered text, writing it to a `@warlock.js/cache`
+* driver with `set({ vector })`, and retrieving by cosine similarity via
+* the driver's `similar()`. Does NOT own: the similarity algorithm or
+* the ANN index — those belong to the cache driver. This mirrors the
+* delegation model of `middleware/builtins/semantic-cache.ts`: memory is
+* embedding-agnostic and store-agnostic, gluing an {@link EmbedderContract}
+* to a {@link CacheDriver}.
+*
+* The driver may be shared across memory instances, so every key carries
+* the configured `namespace` and recall filters hits to that prefix —
+* foreign entries indexed by another instance never leak into a query.
+*
+* Internal to the `memory()` factory — never exported on the package
+* surface.
+*/
+var SemanticMemory = class {
+	constructor(embedder, store, namespace) {
+		this.embedder = embedder;
+		this.store = store;
+		this.namespace = namespace;
+	}
+	/**
+	* Embed the item's text and index it under a namespaced, id-derived
+	* key. Re-remembering the same id overwrites the prior vector +
+	* value (the driver upserts by key).
+	*/
+	async remember(item) {
+		const id = item.id ?? deriveMemoryId(item.text);
+		const { vector } = await this.embedder.embed(item.text);
+		const value = {
+			id,
+			text: item.text,
+			metadata: item.metadata
+		};
+		await this.store.set(this.keyFor(id), value, { vector });
+	}
+	/**
+	* Embed `query`, ask the driver for the `k` nearest entries clearing
+	* `threshold`, and return those within this instance's namespace as
+	* scored {@link RecalledMemory}. Hits indexed under a different
+	* namespace (a shared driver) are filtered out.
+	*/
+	async recall(query, k, threshold) {
+		const { vector } = await this.embedder.embed(query);
+		const hits = await this.store.similar(vector, {
+			topK: k,
+			threshold
+		});
+		const prefix = `${this.namespace}.`;
+		return hits.filter((hit) => hit.key.startsWith(prefix)).map((hit) => ({
+			id: hit.value.id,
+			text: hit.value.text,
+			tier: "semantic",
+			score: hit.score,
+			metadata: hit.value.metadata
+		}));
+	}
+	/** Drop every semantic entry written under this instance's namespace. */
+	async clear() {
+		await this.store.removeNamespace(this.namespace);
+	}
+	/**
+	* Namespaced key for an entry. The cache's `parseKey` normalizes `:`
+	* to `.`, so a dot separator keeps the prefix used here aligned with
+	* the `hit.key` the driver returns from `similar()`.
+	*/
+	keyFor(id) {
+		return `${this.namespace}.${id}`;
+	}
+};
+
+//#endregion
+export { SemanticMemory };
+//# sourceMappingURL=semantic-memory.mjs.map

package/esm/memory/semantic-memory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/semantic-memory.ts"],"sourcesContent":["import type { CacheDriver, CacheSimilarHit } from \"@warlock.js/cache\";\nimport type { EmbedderContract } from \"../contracts/embedder.contract\";\nimport type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport { deriveMemoryId } from \"./derive-id\";\n\n/**\n * Shape persisted per semantic memory in the cache driver. The vector\n * itself is stored by the driver's own index (passed via\n * `set({ vector })`), so it is not duplicated in the value.\n */\ntype StoredMemory = {\n  id: string;\n  text: string;\n  metadata?: Record<string, unknown>;\n};\n\n/**\n * Semantic recall tier (memory core M1).\n *\n * Owns: embedding remembered text, writing it to a `@warlock.js/cache`\n * driver with `set({ vector })`, and retrieving by cosine similarity via\n * the driver's `similar()`. Does NOT own: the similarity algorithm or\n * the ANN index — those belong to the cache driver. This mirrors the\n * delegation model of `middleware/builtins/semantic-cache.ts`: memory is\n * embedding-agnostic and store-agnostic, gluing an {@link EmbedderContract}\n * to a {@link CacheDriver}.\n *\n * The driver may be shared across memory instances, so every key carries\n * the configured `namespace` and recall filters hits to that prefix —\n * foreign entries indexed by another instance never leak into a query.\n *\n * Internal to the `memory()` factory — never exported on the package\n * surface.\n */\nexport class SemanticMemory {\n  public constructor(\n    private readonly embedder: EmbedderContract,\n    private readonly store: CacheDriver<any, any>,\n    private readonly namespace: string,\n  ) {}\n\n  /**\n   * Embed the item's text and index it under a namespaced, id-derived\n   * key. Re-remembering the same id overwrites the prior vector +\n   * value (the driver upserts by key).\n   */\n  public async remember(item: MemoryItem): Promise<void> {\n    const id = item.id ?? deriveMemoryId(item.text);\n    const { vector } = await this.embedder.embed(item.text);\n\n    const value: StoredMemory = {\n      id,\n      text: item.text,\n      metadata: item.metadata,\n    };\n\n    await this.store.set(this.keyFor(id), value, { vector });\n  }\n\n  /**\n   * Embed `query`, ask the driver for the `k` nearest entries clearing\n   * `threshold`, and return those within this instance's namespace as\n   * scored {@link RecalledMemory}. Hits indexed under a different\n   * namespace (a shared driver) are filtered out.\n   */\n  public async recall(\n    query: string,\n    k: number,\n    threshold: number,\n  ): Promise<RecalledMemory[]> {\n    const { vector } = await this.embedder.embed(query);\n\n    const hits = await this.store.similar<StoredMemory>(vector, {\n      topK: k,\n      threshold,\n    });\n\n    const prefix = `${this.namespace}.`;\n\n    return hits\n      .filter((hit: CacheSimilarHit<StoredMemory>) =>\n        hit.key.startsWith(prefix),\n      )\n      .map((hit: CacheSimilarHit<StoredMemory>) => ({\n        id: hit.value.id,\n        text: hit.value.text,\n        tier: \"semantic\" as const,\n        score: hit.score,\n        metadata: hit.value.metadata,\n      }));\n  }\n\n  /** Drop every semantic entry written under this instance's namespace. */\n  public async clear(): Promise<void> {\n    await this.store.removeNamespace(this.namespace);\n  }\n\n  /**\n   * Namespaced key for an entry. The cache's `parseKey` normalizes `:`\n   * to `.`, so a dot separator keeps the prefix used here aligned with\n   * the `hit.key` the driver returns from `similar()`.\n   */\n  private keyFor(id: string): string {\n    return `${this.namespace}.${id}`;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqCA,IAAa,iBAAb,MAA4B;CAC1B,AAAO,YACL,AAAiB,UACjB,AAAiB,OACjB,AAAiB,WACjB;EAHiB;EACA;EACA;CAChB;;;;;;CAOH,MAAa,SAAS,MAAiC;EACrD,MAAM,KAAK,KAAK,MAAM,eAAe,KAAK,IAAI;EAC9C,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,IAAI;EAEtD,MAAM,QAAsB;GAC1B;GACA,MAAM,KAAK;GACX,UAAU,KAAK;EACjB;EAEA,MAAM,KAAK,MAAM,IAAI,KAAK,OAAO,EAAE,GAAG,OAAO,EAAE,OAAO,CAAC;CACzD;;;;;;;CAQA,MAAa,OACX,OACA,GACA,WAC2B;EAC3B,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK;EAElD,MAAM,OAAO,MAAM,KAAK,MAAM,QAAsB,QAAQ;GAC1D,MAAM;GACN;EACF,CAAC;EAED,MAAM,SAAS,GAAG,KAAK,UAAU;EAEjC,OAAO,KACJ,QAAQ,QACP,IAAI,IAAI,WAAW,MAAM,CAC3B,CAAC,CACA,KAAK,SAAwC;GAC5C,IAAI,IAAI,MAAM;GACd,MAAM,IAAI,MAAM;GAChB,MAAM;GACN,OAAO,IAAI;GACX,UAAU,IAAI,MAAM;EACtB,EAAE;CACN;;CAGA,MAAa,QAAuB;EAClC,MAAM,KAAK,MAAM,gBAAgB,KAAK,SAAS;CACjD;;;;;;CAOA,AAAQ,OAAO,IAAoB;EACjC,OAAO,GAAG,KAAK,UAAU,GAAG;CAC9B;AACF"}

package/esm/memory/working-memory.mjs

@@ -0,0 +1,62 @@
+import { deriveMemoryId } from "./derive-id.mjs";
+
+//#region ../@warlock.js/ai/src/memory/working-memory.ts
+/**
+* In-run working memory — the volatile scratch tier (memory core M1).
+*
+* Owns: an insertion-ordered buffer of remembered items keyed by id,
+* with overwrite-in-place on a repeated id. Does NOT own: durability,
+* cross-process sharing, embeddings, or similarity — working memory is
+* a plain in-process buffer the orchestrator threads across the turns of
+* a single run.
+*
+* Recall here is not semantic: with no vector index, "relevant" reduces
+* to "recent." `recall()` returns the most-recently-remembered items
+* first, each scored on a `[0, 1]` recency proxy so a caller can merge
+* working hits with semantic hits and sort on one `score` field.
+*
+* Internal to the `memory()` factory — never exported on the package
+* surface.
+*/
+var WorkingMemory = class {
+	constructor() {
+		this.entries = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Append an item to the buffer (or overwrite the entry sharing its
+	* id). Re-inserting an existing id keeps its original position; delete
+	* + set would move it to the end and lie about recency, so the value
+	* is updated in place.
+	*/
+	remember(item) {
+		const id = item.id ?? deriveMemoryId(item.text);
+		this.entries.set(id, {
+			text: item.text,
+			metadata: item.metadata
+		});
+	}
+	/**
+	* Return up to `k` most-recently-remembered items, newest first. The
+	* `score` is a linear recency proxy: the newest item scores `1`, the
+	* oldest of the returned slice trends toward `0`. Working memory
+	* ignores any similarity threshold — it has no vector to compare.
+	*/
+	recall(k) {
+		const slice = [...this.entries.entries()].reverse().slice(0, Math.max(0, k));
+		return slice.map(([id, entry], index) => ({
+			id,
+			text: entry.text,
+			tier: "working",
+			score: slice.length <= 1 ? 1 : 1 - index / slice.length,
+			metadata: entry.metadata
+		}));
+	}
+	/** Drop every working-tier entry. */
+	clear() {
+		this.entries.clear();
+	}
+};
+
+//#endregion
+export { WorkingMemory };
+//# sourceMappingURL=working-memory.mjs.map

package/esm/memory/working-memory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"working-memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/working-memory.ts"],"sourcesContent":["import type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport { deriveMemoryId } from \"./derive-id\";\n\n/**\n * In-run working memory — the volatile scratch tier (memory core M1).\n *\n * Owns: an insertion-ordered buffer of remembered items keyed by id,\n * with overwrite-in-place on a repeated id. Does NOT own: durability,\n * cross-process sharing, embeddings, or similarity — working memory is\n * a plain in-process buffer the orchestrator threads across the turns of\n * a single run.\n *\n * Recall here is not semantic: with no vector index, \"relevant\" reduces\n * to \"recent.\" `recall()` returns the most-recently-remembered items\n * first, each scored on a `[0, 1]` recency proxy so a caller can merge\n * working hits with semantic hits and sort on one `score` field.\n *\n * Internal to the `memory()` factory — never exported on the package\n * surface.\n */\nexport class WorkingMemory {\n  /**\n   * Id → text/metadata. A `Map` preserves insertion order, so iteration\n   * yields oldest-first; recall reverses it for most-recent-first.\n   */\n  private readonly entries = new Map<\n    string,\n    { text: string; metadata?: Record<string, unknown> }\n  >();\n\n  /**\n   * Append an item to the buffer (or overwrite the entry sharing its\n   * id). Re-inserting an existing id keeps its original position; delete\n   * + set would move it to the end and lie about recency, so the value\n   * is updated in place.\n   */\n  public remember(item: MemoryItem): void {\n    const id = item.id ?? deriveMemoryId(item.text);\n\n    this.entries.set(id, { text: item.text, metadata: item.metadata });\n  }\n\n  /**\n   * Return up to `k` most-recently-remembered items, newest first. The\n   * `score` is a linear recency proxy: the newest item scores `1`, the\n   * oldest of the returned slice trends toward `0`. Working memory\n   * ignores any similarity threshold — it has no vector to compare.\n   */\n  public recall(k: number): RecalledMemory[] {\n    const ordered = [...this.entries.entries()].reverse();\n    const slice = ordered.slice(0, Math.max(0, k));\n\n    return slice.map(([id, entry], index) => ({\n      id,\n      text: entry.text,\n      tier: \"working\" as const,\n      score: slice.length <= 1 ? 1 : 1 - index / slice.length,\n      metadata: entry.metadata,\n    }));\n  }\n\n  /** Drop every working-tier entry. */\n  public clear(): void {\n    this.entries.clear();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAuBA,IAAa,gBAAb,MAA2B;;iCAKE,IAAI,IAG7B;;;;;;;;CAQF,AAAO,SAAS,MAAwB;EACtC,MAAM,KAAK,KAAK,MAAM,eAAe,KAAK,IAAI;EAE9C,KAAK,QAAQ,IAAI,IAAI;GAAE,MAAM,KAAK;GAAM,UAAU,KAAK;EAAS,CAAC;CACnE;;;;;;;CAQA,AAAO,OAAO,GAA6B;EAEzC,MAAM,QADU,CAAC,GAAG,KAAK,QAAQ,QAAQ,CAAC,CAAC,CAAC,QACxB,CAAC,CAAC,MAAM,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC;EAE7C,OAAO,MAAM,KAAK,CAAC,IAAI,QAAQ,WAAW;GACxC;GACA,MAAM,MAAM;GACZ,MAAM;GACN,OAAO,MAAM,UAAU,IAAI,IAAI,IAAI,QAAQ,MAAM;GACjD,UAAU,MAAM;EAClB,EAAE;CACJ;;CAGA,AAAO,QAAc;EACnB,KAAK,QAAQ,MAAM;CACrB;AACF"}

package/esm/middleware/builtins/budget-contract.type.d.mts

@@ -0,0 +1,126 @@
+import { MiddlewareExecuteContext } from "../../contracts/middleware/middleware-context.type.mjs";
+//#region ../@warlock.js/ai/src/middleware/builtins/budget-contract.type.d.ts
+/**
+ * Which SLO dimension of a {@link BudgetContract} a breach belongs to.
+ *
+ * Distinct from `BudgetUnit` (`"tokens" | "usd" | "requests"`) on the
+ * error: `BudgetUnit` is the measurement unit, `BudgetContractDimension`
+ * is the *contract clause* that tripped. They line up for tokens / cost
+ * but diverge for latency — which has no `BudgetUnit` of its own, so a
+ * latency breach surfaces its authoritative detail through the error's
+ * `context.dimension` rather than `error.unit`.
+ */
+type BudgetContractDimension = "tokens" | "cost" | "latency";
+/**
+ * What the middleware does when a {@link BudgetContract} clause is
+ * breached.
+ *
+ * - `"abort"` — throw `BudgetExceededError`, stopping the run at the
+ *   next trip boundary (`result.error` is populated; `execute()` itself
+ *   still never throws). The same hard-stop semantics as the legacy
+ *   `onExceeded: "abort"` path.
+ * - `"fallback"` — do NOT abort. Record a typed {@link BudgetContractViolation}
+ *   signal in the middleware state bag (read it back with
+ *   `readBudgetFallbackSignal`) and invoke the optional `fallback`
+ *   callback, then let the run continue. The middleware cannot itself
+ *   swap models, so a fallback orchestrator / outer layer reads the
+ *   signal and decides how to degrade (cheaper model, cached answer,
+ *   truncated context).
+ */
+type BudgetContractViolationMode = "abort" | "fallback";
+/**
+ * A single recorded breach of a {@link BudgetContract} clause. Captured
+ * verbatim so a fallback layer can branch on the exact dimension and the
+ * numbers that tripped it without re-parsing a message string.
+ *
+ * `limit` and `actual` share the dimension's natural unit: tokens for
+ * `"tokens"`, USD for `"cost"`, milliseconds for `"latency"`.
+ */
+type BudgetContractViolation = {
+  /** Which contract clause tripped. */dimension: BudgetContractDimension; /** The configured cap for the breached dimension. */
+  limit: number; /** The cumulative actual value at the moment of breach. */
+  actual: number; /** Resolved behavior for this breach — mirrors the contract's `onViolation`. */
+  mode: BudgetContractViolationMode;
+};
+/**
+ * Callback fired once when a {@link BudgetContract} clause is breached
+ * under `onViolation: "fallback"`. Receives the recorded violation plus
+ * the run's `execute`-level context so the consumer can read agent /
+ * model identity and the shared state bag.
+ *
+ * Purely a notification hook — its return value is ignored and it cannot
+ * abort the run (throw a typed `AIError` from a guardrail / custom
+ * middleware if a hard stop is required instead). Errors thrown here are
+ * swallowed by the budget middleware so a misbehaving callback cannot
+ * crash the run.
+ */
+type BudgetContractFallback = (violation: BudgetContractViolation, context: MiddlewareExecuteContext) => void | Promise<void>;
+/**
+ * Declarative service-level objective for a single agent run, enforced
+ * by the budget middleware on top of (and independently of) the legacy
+ * `maxTokens` / `maxCostUSD` caps.
+ *
+ * **Role.** Lets a team express a run-level SLO — "this run must cost
+ * under $0.05, finish under 8s, and burn under 40k tokens" — as data,
+ * then pick one global reaction (`abort` hard, or `fallback` soft) for
+ * any clause that trips. The contract is the cost/latency budget the
+ * caller is willing to spend; breaching it is an operational event, not
+ * a user error.
+ *
+ * **Clauses.** Every cap is optional; supply only the dimensions you
+ * care about. A contract with no caps is inert. `maxCostUSD` still needs
+ * a `pricing` entry on `budget()` for the running model — without one,
+ * the cost clause silently degrades (tokens / latency clauses keep
+ * enforcing).
+ *
+ * **Latency.** Wall-clock milliseconds measured from the first
+ * `execute.before` to each `trip.after`. Has no `BudgetUnit`, so a
+ * latency abort surfaces its numbers through the thrown error's
+ * `context` (`{ dimension: "latency", limit, actual }`) rather than
+ * `error.unit`.
+ *
+ * @example
+ * const guard = budget({
+ *   pricing: { "gpt-4o": { inputPer1K: 0.005, outputPer1K: 0.015 } },
+ *   contract: {
+ *     maxCostUSD: 0.05,
+ *     maxLatencyMs: 8_000,
+ *     maxTokens: 40_000,
+ *     onViolation: "fallback",
+ *     fallback: (violation) => routeToCheaperModel(violation.dimension),
+ *   },
+ * });
+ */
+type BudgetContract = {
+  /**
+   * Cumulative total-token cap for the run. Independent of the
+   * top-level `BudgetOptions.maxTokens`; whichever trips first wins.
+   */
+  maxTokens?: number;
+  /**
+   * Cumulative USD-cost cap for the run. Requires `BudgetOptions.pricing`
+   * for the running model — degrades silently without it, same as the
+   * legacy cost cap.
+   */
+  maxCostUSD?: number;
+  /**
+   * Wall-clock latency cap in milliseconds, measured from the run start
+   * to each completed trip. Breached when cumulative elapsed time
+   * exceeds the cap at a trip boundary.
+   */
+  maxLatencyMs?: number;
+  /**
+   * Reaction applied to every clause of this contract. Default
+   * `"abort"`. `"fallback"` records a signal + fires `fallback` and
+   * lets the run continue.
+   */
+  onViolation?: BudgetContractViolationMode;
+  /**
+   * Notification callback fired on the first breach under
+   * `onViolation: "fallback"`. Ignored when `onViolation` is `"abort"`.
+   */
+  fallback?: BudgetContractFallback;
+};
+//#endregion
+export { BudgetContract, BudgetContractDimension, BudgetContractFallback, BudgetContractViolation, BudgetContractViolationMode };
+//# sourceMappingURL=budget-contract.type.d.mts.map

package/esm/middleware/builtins/budget-contract.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-contract.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/budget-contract.type.ts"],"mappings":";;;;;AAYA;;;;AAAmC;AAkBnC;;KAlBY,uBAAA;;AAkB2B;AAUvC;;;;;;;;;;;AAQmC;AAenC;;KAjCY,2BAAA;;;;;;;;;KAUA,uBAAA;EA0BA,qCAxBV,SAAA,EAAW,uBAAA,EAwBM;EAtBjB,KAAA,UA4DwB;EA1DxB,MAAA,UAsFiC;EApFjC,IAAA,EAAM,2BAA2B;AAAA;;;;;;;AAoFA;;;;;;KArEvB,sBAAA,IACV,SAAA,EAAW,uBAAA,EACX,OAAA,EAAS,wBAAA,YACC,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAsCA,cAAA;;;;;EAKV,SAAA;;;;;;EAMA,UAAA;;;;;;EAMA,YAAA;;;;;;EAMA,WAAA,GAAc,2BAAA;;;;;EAKd,QAAA,GAAW,sBAAsB;AAAA"}