@ultimat3/ai 11.2.0 → 12.0.0

package/CLAUDE.md

@@ -80,6 +80,17 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
 - Semantic scopes are separate cache INSTANCES, never a filter over a shared one — cosine
   similarity has no notion of a tenant. The instance key carries the prompt hash too, which is
   what makes a version bump invalidate the cache.
+- **The instance key carries `ctx.locale` too, `As of 2026-08-24`, and it sits with the prompt hash
+  rather than with the scope.** A prompt taking `locale` as a var — the reference app's `summarize`
+  does, and the model obeys it — differs by ONE token between languages while carrying a whole
+  document, so the two rendered prompts are neighbours: measured with this package's own
+  `HashEmbedder` over that template, **0.9986**, against the declaration's `threshold: 0.97`. The
+  Spanish summary was a hit for an English reader, and the model was never wrong — the cache was.
+  No threshold repairs it, because the same number has to keep an honest repeat above it. It is in
+  the UNCONDITIONAL half of the key because a `scope` answers "who may share this answer" and a
+  locale is part of what the answer IS: an app writing `scope: () => 'global'` is saying its
+  callers may read one another's summaries, never that a Spanish one will do. Same rule
+  `@ultimat3/render` applies to ISR.
 - **The default scope is the calling ACTOR, and `scope` receives `{ input, ctx }`** (`As of
   2026-08`). It defaulted to the literal string `'global'` and took the bare `input`, so the rule
   in the bullet above was contradicted by the very default that shipped: `cache: { semantic: { ttl:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "11.2.0",
+  "version": "12.0.0",
   "description": "LLM gateway, versioned prompts, evals as tests, embeddings, hybrid vector search, RAG",
   "license": "MIT",
   "type": "module",
@@ -32,14 +32,14 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "11.2.0",
-    "@ultimat3/cache": "11.2.0",
-    "@ultimat3/core": "11.2.0",
-    "@ultimat3/db": "11.2.0",
-    "@ultimat3/jobs": "11.2.0",
-    "@ultimat3/money": "11.2.0",
-    "@ultimat3/policy": "11.2.0",
-    "@ultimat3/schema": "11.2.0",
-    "@ultimat3/time": "11.2.0"
+    "@ultimat3/action": "12.0.0",
+    "@ultimat3/cache": "12.0.0",
+    "@ultimat3/core": "12.0.0",
+    "@ultimat3/db": "12.0.0",
+    "@ultimat3/jobs": "12.0.0",
+    "@ultimat3/money": "12.0.0",
+    "@ultimat3/policy": "12.0.0",
+    "@ultimat3/schema": "12.0.0",
+    "@ultimat3/time": "12.0.0"
   }
 }

package/src/llm-cache.ts

@@ -6,6 +6,13 @@
  * carries the prompt VERSION as well — which is what makes "editing a prompt requires a version
  * bump" invalidate the cache: a bumped version reaches a different store, so an old answer cannot
  * survive a prompt edit no matter how similar the text.
+ *
+ * It carries the request LOCALE for the same structural reason, `As of 2026-08-24`. A prompt that
+ * takes `locale` as a var — the reference app's `summarize` does, and the model obeys it — differs
+ * by one token between languages while carrying a whole document, so the two renderings are
+ * neighbours: measured with this package's own `HashEmbedder` over that template, **0.9986**
+ * against a declared threshold of `0.97`. The Spanish answer was therefore a hit for an English
+ * reader. No threshold fixes it, because the same number has to keep an honest repeat above it.
  */
 
 import type { Ctx } from '@ultimat3/core';
@@ -62,6 +69,10 @@ export interface PromptCache {
  * same reason it is JSON rather than a joined string — an actor id is app data and may carry any
  * separator, and a value that can spell a boundary can spell somebody else's.
  *
+ * The locale is deliberately NOT here. This function is the DEFAULT a declaration replaces by
+ * writing its own `scope`, and the locale has to survive that — so it lives in the unconditional
+ * half of the store key, beside the prompt hash.
+ *
  * `ctx.actor` is never absent (`createContext` defaults it to `anonymousActor()`), so every
  * anonymous caller shares one partition — which is what the anonymous actor already means
  * everywhere else in the framework.
@@ -92,7 +103,14 @@ export async function openCache<TParsed>(
   const semantic = args.cache?.semantic;
   if (semantic === undefined) return undefined;
   const scope = semantic.scope?.({ input: args.input, ctx: args.ctx }) ?? actorScope(args.ctx);
-  const store = semanticCacheFor(`${args.prompt.ref}#${args.prompt.hash}::${scope}`);
+  // The locale sits with the prompt HASH and not with the scope, on purpose: a scope answers "who
+  // may share this answer" and the locale is part of what the answer IS — so a written-down
+  // `scope: () => 'global'` is still partitioned by it. An app declaring a shared store is saying
+  // its callers may read one another's summaries, never that a Spanish one will do for an English
+  // reader. `@ultimat3/render`'s ISR keys by locale for exactly this reason.
+  const store = semanticCacheFor(
+    `${args.prompt.ref}#${args.prompt.hash}@${args.ctx.locale}::${scope}`,
+  );
   const embedding = Array.from(await embedOne(aiEmbedder(), args.rendered));
   const ttlMs = semantic.ttl === undefined ? undefined : parseDuration(semantic.ttl);
   return {