agentfootprint 9.28.0 → 9.30.0

package/dist/adapters/llm/googleGenAI.js

@@ -28,10 +28,63 @@
  * `test/adapters/google/google-surface-pin.test.ts`. It is not `v1`. Callers
  * who need a specific version pass `apiVersion`; callers who do not at least
  * find the truth stated instead of assuming a GA path.
+ *
+ * ─── The key can be a CALLBACK, and why (9.29.0) ────────────────────
+ *
+ * `GoogleGenAIOptions.apiKey` is `string` on the installed SDK (@google/genai
+ * 2.16.0 `genai.d.ts`) — one value, fixed at construction. That is fine for an
+ * AI Studio key, which does not expire, and wrong for every credential that
+ * does: a Vertex OAuth access token lives about an hour, and a key pulled from
+ * a secret manager is rotated on somebody else's schedule.
+ *
+ * An independent field trial on live GCP measured exactly that boundary: an
+ * OAuth token that worked returned HTTP 401 once expired, with no place in the
+ * options to put a fresh one ("Part 2B — ADC refresh versus OpenAI-compatible
+ * OAuth"). So `apiKey` widens to `string | (() => string | Promise<string>)`,
+ * and the refresh boundary is stated rather than implied:
+ *
+ *   • The callback runs ONCE PER REQUEST, before the request is built.
+ *   • The SDK client is REBUILT only when the returned string differs from the
+ *     one already in hand — a callback that returns a cached token costs one
+ *     function call and nothing else.
+ *   • A stream keeps the key it STARTED with. The boundary is the call, not
+ *     the chunk; nothing here can re-authenticate a socket that is already
+ *     open.
+ *   • Vertex needs none of this. ADC refreshes itself, which the same trial
+ *     verified by forcing an in-memory expiry and completing the next call.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveGoogleGenAIClient = void 0;
+exports.createGoogleGenAIClientResolver = exports.resolveGoogleGenAIClient = exports.resolveGoogleDoor = void 0;
 const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
+/** An empty environment variable is not a setting — see `resolveGoogleGenAIClient`. */
+const set = (value) => value !== undefined && value.trim().length > 0 ? value : undefined;
+/** The env this module reads, or `{}` off-Node. */
+const environment = () => (typeof process !== 'undefined' ? process.env : {});
+/**
+ * Which door these options open.
+ *
+ * The order mirrors `resolveGoogleGenAIClient` exactly, because a door that
+ * disagreed with the client that gets built is worse than no door at all.
+ *
+ * @param readEnv `false` when the caller injected a `_client`. A double talks
+ *        to no service, so the ambient `GEMINI_API_KEY` of whoever is running
+ *        the tests describes a door that will never be dialled — reading it
+ *        would make an offline suite depend on a developer's shell.
+ */
+function resolveGoogleDoor(options, readEnv = true) {
+    if (options.vertexai === true)
+        return 'vertex';
+    if (options.vertexai === false)
+        return 'gemini-api';
+    const env = readEnv ? environment() : {};
+    if ((set(options.project) ?? set(env.GOOGLE_CLOUD_PROJECT)) !== undefined)
+        return 'vertex';
+    const key = (typeof options.apiKey === 'function' ? 'callback' : set(options.apiKey)) ??
+        set(env.GEMINI_API_KEY) ??
+        set(env.GOOGLE_API_KEY);
+    return key !== undefined ? 'gemini-api' : 'vertex';
+}
+exports.resolveGoogleDoor = resolveGoogleDoor;
 /**
  * Build (or accept) a `GoogleGenAI` client.
  *
@@ -43,14 +96,18 @@ const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
  * @param factory  the public name to put in refusals — `'gemini'`,
  *                 `'geminiEmbedder'`. A message that names the wrong factory
  *                 sends the reader to the wrong line of their own code.
+ * @param apiKey   the key STRING for this build. Callers holding a callback
+ *                 resolve it first (see {@link createGoogleGenAIClientResolver});
+ *                 a function reaching the SDK's `apiKey` field would be sent
+ *                 as `[object Function]` and fail as an auth error.
  * @throws when neither a project nor an API key is resolvable; when
  *         `vertexai: true` is asked for without a project; and when
  *         `@google/genai` is not installed.
  */
-function resolveGoogleGenAIClient(options, factory, injected) {
+function resolveGoogleGenAIClient(options, factory, injected, apiKey) {
     if (injected)
         return injected;
-    const env = (typeof process !== 'undefined' ? process.env : {});
+    const env = environment();
     // Read HERE only to decide whether there is enough configuration to build
     // anything at all. The values are never copied into the constructor, so the
     // SDK stays the single resolver of its own environment variables — one place
@@ -58,11 +115,13 @@ function resolveGoogleGenAIClient(options, factory, injected) {
     // An EMPTY variable is not a setting. `GOOGLE_CLOUD_PROJECT=` in a shell or a
     // CI matrix is how a project comes to be "present" and unusable — the guards
     // below would pass and the SDK would fail on the first call instead.
-    const set = (value) => value !== undefined && value.trim().length > 0 ? value : undefined;
     const project = set(options.project) ?? set(env.GOOGLE_CLOUD_PROJECT);
-    const apiKey = set(options.apiKey) ?? set(env.GEMINI_API_KEY) ?? set(env.GOOGLE_API_KEY);
+    const resolvedKey = set(apiKey) ??
+        (typeof options.apiKey === 'string' ? set(options.apiKey) : undefined) ??
+        set(env.GEMINI_API_KEY) ??
+        set(env.GOOGLE_API_KEY);
     const vertexai = options.vertexai ?? (project !== undefined ? true : undefined);
-    if (vertexai !== false && project === undefined && apiKey === undefined) {
+    if (vertexai !== false && project === undefined && resolvedKey === undefined) {
         throw new Error(`${factory}: no Google project and no API key — this factory cannot tell which service ` +
             'you meant, and the SDK would warn on stderr, construct anyway, and fail on the first ' +
             'call with something that reads like a network problem.\n' +
@@ -93,12 +152,15 @@ function resolveGoogleGenAIClient(options, factory, injected) {
             'are built against @google/genai 2.x — update the package.');
     }
     // Only what was ASKED for goes on the wire; everything omitted is left to the
-    // SDK's own environment resolution.
+    // SDK's own environment resolution. The key is the one exception: the
+    // CALLBACK form has already been called by the time we get here, so what
+    // travels is the string it answered with — never the function.
+    const key = apiKey ?? (typeof options.apiKey === 'string' ? options.apiKey : undefined);
     return new GoogleGenAI({
         ...(vertexai !== undefined && { vertexai }),
         ...(options.project !== undefined && { project: options.project }),
         ...(options.location !== undefined && { location: options.location }),
-        ...(options.apiKey !== undefined && { apiKey: options.apiKey }),
+        ...(key !== undefined && { apiKey: key }),
         ...(options.apiVersion !== undefined && { apiVersion: options.apiVersion }),
         ...(options.googleAuthOptions !== undefined && {
             googleAuthOptions: options.googleAuthOptions,
@@ -106,4 +168,89 @@ function resolveGoogleGenAIClient(options, factory, injected) {
     });
 }
 exports.resolveGoogleGenAIClient = resolveGoogleGenAIClient;
+/**
+ * The client seam every Google adapter calls through — one per request.
+ *
+ * Three paths, and only the third one is new:
+ *
+ *  1. **`_client` injected** — the double, always, no SDK, no environment.
+ *     Any `apiKey` still rides along on the lease so redaction tests can
+ *     prove a secret never reaches an error message.
+ *  2. **`apiKey` a string (or absent)** — the client is built ONCE. With
+ *     `eager`, it is built at factory time, so a missing peer dependency and
+ *     an unanswerable door are still refused where the consumer typed the
+ *     call rather than on their first request.
+ *  3. **`apiKey` a callback** — called before every request. The client is
+ *     rebuilt only when the answer CHANGED, so a cached token costs one
+ *     function call. Construction cannot be eager here: calling a consumer's
+ *     credential provider from a factory would fetch a token nobody asked
+ *     for yet, and possibly before their own setup ran.
+ *
+ * @param eager build now (path 2 only), preserving construction-time refusals.
+ */
+function createGoogleGenAIClientResolver(options, factory, injected, eager = false) {
+    const source = options.apiKey;
+    if (injected) {
+        // A double stands in for the SDK CLIENT, not for the credential. So a
+        // callback is still called per request here: it is the only way a test can
+        // watch a key rotate, and the only way redaction can be proved against the
+        // key that is actually in force rather than the one at construction.
+        if (typeof source !== 'function') {
+            const lease = {
+                client: injected,
+                ...(source !== undefined && { apiKey: source }),
+            };
+            return async () => lease;
+        }
+        return async () => ({ client: injected, apiKey: await resolveKey(source, factory) });
+    }
+    if (typeof source !== 'function') {
+        let built = eager
+            ? resolveGoogleGenAIClient(options, factory, undefined)
+            : undefined;
+        return async () => {
+            built ??= resolveGoogleGenAIClient(options, factory, undefined);
+            return { client: built, ...(source !== undefined && { apiKey: source }) };
+        };
+    }
+    // The callback path. `lastKey` is held so the SDK client survives a callback
+    // that keeps answering the same thing — which is what a well-behaved token
+    // cache does on all but one call in a thousand.
+    let lastKey;
+    let built;
+    return async () => {
+        const answer = await resolveKey(source, factory);
+        if (built === undefined || answer !== lastKey) {
+            built = resolveGoogleGenAIClient(options, factory, undefined, answer);
+            lastKey = answer;
+        }
+        return { client: built, apiKey: answer };
+    };
+}
+exports.createGoogleGenAIClientResolver = createGoogleGenAIClientResolver;
+/** Call the credential callback and insist on something usable. */
+async function resolveKey(source, factory) {
+    const answer = await source();
+    if (typeof answer === 'string' && answer.trim().length > 0)
+        return answer;
+    // The value is NOT quoted back. It is a credential when it is right, and it
+    // is whatever the consumer's provider returned when it is wrong; a message
+    // that printed it would be the one place this library leaks one.
+    throw new Error(`${factory}: the \`apiKey\` callback returned ${describeKey(answer)}, and a key has to be a ` +
+        'non-empty string.\n' +
+        '  The callback is called before every request, so this is a live credential failure, ' +
+        'not a configuration one — a token fetch that failed usually throws rather than returning ' +
+        'nothing.\n' +
+        `  Fix:  return the token, or throw from the callback so ${factory} can report why.`);
+}
+/** What came back, said without saying it. */
+function describeKey(value) {
+    if (typeof value === 'string')
+        return 'an empty string';
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    return `a ${typeof value}`;
+}
 //# sourceMappingURL=googleGenAI.js.map

package/dist/adapters/llm/googleGenAI.js.map

@@ -1 +1 @@
-{"version":3,"file":"googleGenAI.js","sourceRoot":"","sources":["../../../src/adapters/llm/googleGenAI.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"googleGenAI.js","sourceRoot":"","sources":["../../../src/adapters/llm/googleGenAI.ts"],"names":[],"mappings":"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"}

package/dist/adapters/memory/memoryBank.js

@@ -65,6 +65,22 @@
  * before every overwrite — so even an address collision is refused rather than
  * written through.
  *
+ * ── The retrieved NAME is not the name you wrote ────────────────────────────
+ * A live field trial on the raw service found this and it is worth stating,
+ * because it is exactly the assumption an adapter is tempted to make: `create`
+ * and `list` came back with the caller-chosen memory ids, while SIMILARITY
+ * RETRIEVAL answered with generated numeric resource names for the very same
+ * facts (FINDINGS "Agent Runtime Memory Bank"). Anything reading an entry id
+ * out of `memory.name` would therefore work perfectly on `list()` and hand back
+ * unusable ids from `search()` — ids that no `get()` or `delete()` could find.
+ *
+ * This adapter never does that: `toEntry` reads the id from the metadata this
+ * library wrote, and the resource name is carried only as
+ * `entry.metadata.resourceName`, for looking at. The same trial also confirmed
+ * exact-match scope semantics (a partial `{tenant}` scope retrieved nothing)
+ * and the distance-not-similarity ranking that {@link MemoryBankStore.search}
+ * converts.
+ *
  * ── Writes are long-running operations ──────────────────────────────────────
  * `create`, `patch` and `delete` all answer with an Operation rather than the
  * resource — verified against the installed SDK's own return types. Every
@@ -88,7 +104,7 @@
  * through the shared REST client in `adapters/google/aiPlatform.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.scoreFromDistance = exports.memoryBankStore = exports.MemoryBankStore = exports.MAX_PAGE_SIZE = void 0;
+exports.scoreFromDistance = exports.memoryBankStore = exports.MemoryBankStore = exports.MAX_PAGE_SIZE = exports.MAX_CARRIED_JSON = void 0;
 const aiPlatform_js_1 = require("../google/aiPlatform.js");
 const ADAPTER = 'memoryBankStore';
 /**
@@ -107,7 +123,44 @@ const META = {
     updatedAt: 'agentfootprint_updated_at',
     tier: 'agentfootprint_tier',
     json: 'agentfootprint_json',
+    /** {@link MemoryEntry.source}, verbatim, as JSON. See {@link MAX_CARRIED_JSON}. */
+    source: 'agentfootprint_source',
+    /** {@link MemoryEntry.metadata} the CALLER wrote, verbatim, as JSON. */
+    meta: 'agentfootprint_metadata',
+    /** {@link MemoryEntry.decayPolicy}, as JSON — retrieval ranking depends on it. */
+    decay: 'agentfootprint_decay',
 };
+/**
+ * The metadata keys this adapter GENERATES on the way out, which therefore
+ * cannot also be caller metadata.
+ *
+ * They are read-side facts about the row, not stored data: `source` names the
+ * backend, `resourceName` is the Vertex name, `distance` is the raw retrieval
+ * distance. Round-tripping an entry this store handed back must not fail, and
+ * a caller's own value under one of these names must not be silently replaced
+ * — see {@link splitMetadata} for how those two are told apart.
+ */
+const GENERATED_METADATA = ['source', 'resourceName', 'distance'];
+/**
+ * What a Vertex resource name for a memory looks like:
+ * `projects/<p>/locations/<l>/reasoningEngines/<e>/memories/<resource id>`.
+ *
+ * Used as the SHAPE half of recognising this adapter's own `resourceName` on the
+ * way back in — never as a parser. Nothing reads an id out of a resource name
+ * here (the module header says why); this only answers "could this string be one
+ * of ours?".
+ */
+const RESOURCE_NAME = /^projects\/.+\/memories\/[^/]+$/;
+/**
+ * The most JSON one carried field may be, in characters.
+ *
+ * Memory Bank metadata values are typed scalars and this column has NOT
+ * measured the service's own ceiling on a string one, so the bound is this
+ * adapter's own and says so where it refuses. It is a refusal rather than a
+ * truncation on purpose: provenance that came back shortened would be
+ * provenance nobody could tell was shortened.
+ */
+exports.MAX_CARRIED_JSON = 8_192;
 /** The service's own ceiling on a page or a top-k. Larger values are coerced. */
 exports.MAX_PAGE_SIZE = 100;
 /** What a `list()` page carries when nothing was asked for. */
@@ -115,9 +168,22 @@ const DEFAULT_PAGE_SIZE = 20;
 /**
  * A `MemoryStore` over Vertex AI Memory Bank.
  *
- * **Status: contract-shaped and tested; awaiting field use.** Every call is
- * exercised through an injected client and pinned against the really-installed
- * SDK. None of it has yet answered a request from Google in a real project.
+ * **Status: field-validated on the data plane (2026-08-14).** An independent
+ * trial ran THIS class against a real Memory Bank and every one of these
+ * answered a live request: the honest `supportsVectorSearch: false` /
+ * `ranksBy: 'server-text'` declarations; cross-conversation recall under a
+ * widened `scopeFor`; two identities using the SAME entry id without collision
+ * or disclosure; string and structured values; opaque pagination cursors; tier
+ * filtering; text similarity that found the right marker, excluded the other
+ * identity, returned finite distances and converted them to correctly ORDERED
+ * scores; overwrite advancing value and version; a scoped delete leaving the
+ * other identity intact; `forget()` erasing across the widened scope; and the
+ * five unsupported operations refusing by name rather than pretending.
+ *
+ * The same trial found the one thing that was NOT faithful — `source` and
+ * caller `metadata` were accepted and silently dropped — which 9.30.0 fixes by
+ * carrying them (see `toMemory`). That fix is tested here and has not itself
+ * been re-run in a live project.
  */
 class MemoryBankStore {
     /**
@@ -732,10 +798,29 @@ const num = (value) => ({ doubleValue: value });
  * retrieval over structured values is close to meaningless. Store a sentence
  * when you want it found.
  *
- * `embedding` is deliberately dropped — see `supportsVectorSearch`.
+ * ── What is CARRIED, and why it took a field trial ──────────────────────────
+ * `source`, the caller's own `metadata` and `decayPolicy` are stored as JSON
+ * under prefixed keys of ours and restored verbatim on the way back.
+ *
+ * They were dropped until 9.30.0, and an independent trial (2026-08-14) is what
+ * made that visible: an entry written with `source.turn`, `source.messageId`
+ * and `metadata.classification` came back carrying only this adapter's own
+ * metadata. That is a contract failure and not merely a gap —
+ * `MemorySource.identity` is documented as a field "storage adapters MUST
+ * preserve verbatim on every read/write", and the fields feed audit, causal
+ * chains, decay and retrieval policy. A store that accepts them, reports
+ * success and silently forgets them is the exact shape of wrongness this
+ * library refuses everywhere else.
+ *
+ * `embedding` and `embeddingModel` are the ONE pair still dropped, and that is
+ * a refusal rather than an oversight: there is nowhere to put a vector here and
+ * nothing that would rank it (see `supportsVectorSearch`), and a stored
+ * `embeddingModel` with no vector beside it would claim a compatibility that
+ * does not exist.
  */
 function toMemory(entry, scope, defaultTtl) {
     const isString = typeof entry.value === 'string';
+    const carried = splitMetadata(entry);
     const metadata = {
         [META.id]: str(entry.id),
         [META.version]: num(entry.version),
@@ -743,6 +828,15 @@ function toMemory(entry, scope, defaultTtl) {
         [META.updatedAt]: num(entry.updatedAt),
         [META.json]: { boolValue: !isString },
         ...(entry.tier !== undefined && { [META.tier]: str(entry.tier) }),
+        ...(entry.source !== undefined && {
+            [META.source]: str(carriedJson(entry.source, 'source', entry.id)),
+        }),
+        ...(carried !== undefined && {
+            [META.meta]: str(carriedJson(carried, 'metadata', entry.id)),
+        }),
+        ...(entry.decayPolicy !== undefined && {
+            [META.decay]: str(carriedJson(entry.decayPolicy, 'decayPolicy', entry.id)),
+        }),
     };
     return {
         fact: isString ? entry.value : JSON.stringify(entry.value ?? null),
@@ -756,6 +850,128 @@ function toMemory(entry, scope, defaultTtl) {
             : defaultTtl !== undefined && { ttl: defaultTtl }),
     };
 }
+/**
+ * The caller's own metadata, with this adapter's generated keys separated out
+ * — or `undefined` when there is none to carry.
+ *
+ * The three keys in {@link GENERATED_METADATA} are produced on every read, so
+ * an entry that came out of this store carries them and a `get`-then-`put`
+ * round trip hands them straight back. Two cases, told apart rather than
+ * conflated:
+ *
+ *  • **It is one of ours coming home** — recognised by IDENTITY, not by shape.
+ *    See {@link isGeneratedValue}.
+ *  • **It is the caller's own value** under one of those names — refused by
+ *    name. Storing it would mean the next read silently answered with our
+ *    value instead of theirs, which is the failure mode this whole function
+ *    exists to end.
+ */
+function splitMetadata(entry) {
+    const metadata = entry.metadata;
+    if (metadata === undefined || metadata === null)
+        return undefined;
+    // `toEntry` stamps `source` on EVERY read, so its presence — with exactly the
+    // backend name this store writes — is what distinguishes an entry coming home
+    // from a caller who happened to pick one of our key names. Computed once for
+    // the whole bag, because it is a fact about the ENTRY, not about a key.
+    const ours = metadata['source'] === BACKEND_NAME;
+    const kept = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (!GENERATED_METADATA.includes(key)) {
+            kept[key] = value;
+            continue;
+        }
+        if (isGeneratedValue(key, value, ours))
+            continue;
+        throw metadataKeyConflict(entry.id, key, value, ours);
+    }
+    return Object.keys(kept).length === 0 ? undefined : kept;
+}
+/**
+ * Is this the value THIS adapter put under that key on a read — or the caller's
+ * own, wearing one of our names?
+ *
+ * **Recognition is by identity, not by shape**, and the difference is a bug this
+ * adapter shipped once. A shape test asks "is `resourceName` a string, is
+ * `distance` a number?" — which every string and every number passes, so a
+ * caller's `metadata.resourceName = 'sku-42'` or `metadata.distance = 12` was
+ * accepted as ours, dropped, and answered on the next read with THIS adapter's
+ * resourceName sitting where their value had been. That is precisely the
+ * accepted-and-silently-wrong failure {@link metadataKeyConflict} exists to
+ * refuse, and a shape test could not tell the two apart even in principle
+ * (finding 29, 2026-08-14 field trial).
+ *
+ * So the test is: `source` must be exactly {@link BACKEND_NAME} — the stamp
+ * `toEntry` writes on every read and nothing else does — and `resourceName` /
+ * `distance` count as ours only when that stamp RIDES WITH THEM on the same
+ * entry, and the value itself still has the right shape (a Vertex resource name;
+ * a number). Both halves are needed: the stamp says "this entry came from here",
+ * the shape says "and this field was not overwritten since".
+ *
+ * The one ambiguity left is honest and narrow: a caller who takes an entry out
+ * of this store and writes their OWN number into `metadata.distance` before
+ * putting it back is indistinguishable from the retrieval distance that came
+ * with it, and is dropped. Keep such a value under a name of your own.
+ */
+function isGeneratedValue(key, value, ours) {
+    if (key === 'source')
+        return value === BACKEND_NAME;
+    if (!ours)
+        return false;
+    if (key === 'resourceName')
+        return typeof value === 'string' && RESOURCE_NAME.test(value);
+    return typeof value === 'number';
+}
+/**
+ * A caller's metadata key collides with one this adapter generates on every read.
+ *
+ * `ours` says whether the entry carried this store's own `source` stamp, which
+ * decides WHICH of the two things went wrong — a name collision, or a value
+ * edited into a round-tripped entry — and therefore what the reader should do.
+ */
+function metadataKeyConflict(id, key, value, ours) {
+    const err = new Error(
+    // The caller's own value, echoed back short: enough to recognise which
+    // field this is, never enough to paste a whole payload into a log line
+    // that an error reaches more sinks than the writer expects.
+    `${ADAPTER}: entry '${id}' carries metadata.${key} = ${shortly(value)}, and this ` +
+        `adapter GENERATES metadata.${key} on every read.\n` +
+        `  Storing it would mean your value went in and this adapter's came back — a read that ` +
+        `looks right and is not. The three generated keys are: ` +
+        `${GENERATED_METADATA.join(', ')} (the backend name, the Vertex resource name, and the ` +
+        `raw retrieval distance).\n` +
+        (ours
+            ? `  This entry does carry this store's own metadata.source = '${BACKEND_NAME}', so it ` +
+                `came from here — but this particular value is not the one this adapter wrote ` +
+                `(a resourceName must look like 'projects/…/memories/<id>'; a distance must be a ` +
+                `number). It is refused rather than dropped, because dropping a value somebody ` +
+                `deliberately set is the same silent wrongness in the other direction.\n`
+            : '') +
+        `  Fix: rename the key on your entry. Values this store itself produced are recognised ` +
+        `and dropped instead, so reading an entry and writing it back is always safe.`);
+    err.name = 'MemoryMetadataConflictError';
+    return err;
+}
+/** A value as at most 80 characters of JSON, for a refusal to point with. */
+function shortly(value) {
+    const json = JSON.stringify(value) ?? String(value);
+    return json.length <= 80 ? json : `${json.slice(0, 77)}…`;
+}
+/** One carried field as JSON, or a refusal that says which field and how big. */
+function carriedJson(value, field, id) {
+    const json = JSON.stringify(value ?? null);
+    if (json.length <= exports.MAX_CARRIED_JSON)
+        return json;
+    throw new RangeError(`${ADAPTER}: entry '${id}' has a '${field}' of ${json.length} JSON characters, over this ` +
+        `adapter's ${exports.MAX_CARRIED_JSON}-character bound for a carried field.\n` +
+        `  Memory Bank stores these as metadata STRINGS, and the service's own ceiling on one is ` +
+        `not measured by this library — so the bound is ours and deliberately conservative.\n` +
+        `  It refuses rather than truncating: provenance that came back shortened would be ` +
+        `provenance nothing could tell was shortened. Keep large payloads in the entry VALUE, ` +
+        `which becomes the memory's fact.`);
+}
+/** What this adapter names itself as the backend, in a returned entry's metadata. */
+const BACKEND_NAME = 'vertex-memory-bank';
 /**
  * `Memory` → `MemoryEntry`, or `null` for a row this store did not write.
  *
@@ -788,6 +1004,9 @@ function toEntry(memory, retrieved) {
     const updatedAt = metadata[META.updatedAt]?.doubleValue ?? toMillis(memory.updateTime);
     const tier = metadata[META.tier]?.stringValue;
     const expireTime = toMillis(memory.expireTime);
+    const source = carriedBack(metadata[META.source]?.stringValue);
+    const callerMetadata = carriedBack(metadata[META.meta]?.stringValue);
+    const decayPolicy = carriedBack(metadata[META.decay]?.stringValue);
     return {
         id,
         value: value,
@@ -798,8 +1017,14 @@ function toEntry(memory, retrieved) {
         accessCount: 0,
         ...(expireTime > 0 && { ttl: expireTime }),
         ...(tier === 'hot' || tier === 'warm' || tier === 'cold' ? { tier } : {}),
+        ...(source !== undefined && { source }),
+        ...(decayPolicy !== undefined && { decayPolicy }),
         metadata: {
-            source: 'vertex-memory-bank',
+            // The caller's own metadata first, then this adapter's generated facts.
+            // They cannot collide: a caller value under a generated key is refused at
+            // write time rather than overwritten here (see splitMetadata).
+            ...callerMetadata,
+            source: BACKEND_NAME,
             ...(memory.name !== null && memory.name !== undefined && { resourceName: memory.name }),
             // The raw distance, carried through unmodified — the honest number
             // beside the converted one, for a caller who knows the metric.
@@ -807,6 +1032,25 @@ function toEntry(memory, retrieved) {
         },
     };
 }
+/**
+ * One carried JSON field on the way back, or `undefined`.
+ *
+ * Unparseable JSON answers `undefined` rather than raising: the bytes were
+ * written by an older release of this adapter or edited in the console, and a
+ * memory that EXISTS must not read as one that was never written over a
+ * damaged provenance field. The entry's own value is unaffected.
+ */
+function carriedBack(json) {
+    if (typeof json !== 'string' || json === '')
+        return undefined;
+    try {
+        const parsed = JSON.parse(json);
+        return parsed === null ? undefined : parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** An RFC 3339 timestamp as unix milliseconds, or 0 when it is not one. */
 function toMillis(value) {
     if (typeof value !== 'string')