@rotifer/playground 0.32.1 → 0.33.0

package/dist/memory/codec.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RETENTION_DAYS = exports.MAX_KEY_BYTES = void 0;
+exports.entryIdFor = entryIdFor;
+exports.encodeValue = encodeValue;
+exports.decodeValue = decodeValue;
+exports.checkKey = checkKey;
+exports.checkAccessPolicy = checkAccessPolicy;
+exports.checkRetentionPolicy = checkRetentionPolicy;
+exports.toTimestamp = toTimestamp;
+exports.parseTimestamp = parseTimestamp;
+exports.toEntryJson = toEntryJson;
+exports.fromEntryJson = fromEntryJson;
+exports.parseMemoryQuota = parseMemoryQuota;
+exports.entrySize = entrySize;
+exports.isV2GeneId = isV2GeneId;
+/**
+ * Conversions at the AgentMemory boundary: entry ids, base64
+ * values, the JSON shape of an entry, timestamps and the quota size syntax.
+ * Anything that does not parse is MEMORY_INVALID_INPUT, never coerced.
+ */
+const node_crypto_1 = require("node:crypto");
+const types_js_1 = require("./types.js");
+/** Lowercase hex SHA-256 of `agentId + "\0" + key`. Updates keep the id. */
+function entryIdFor(agentId, key) {
+    return (0, node_crypto_1.createHash)("sha256").update(`${agentId}\0${key}`, "utf8").digest("hex");
+}
+// Standard alphabet, padded: the same in every binding.
+// Buffer.from(…, "base64") would also accept base64url, missing padding and
+// stray characters, and silently decode something else.
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+function encodeValue(value) {
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength).toString("base64");
+}
+function decodeValue(base64) {
+    if (typeof base64 !== "string" || !BASE64.test(base64)) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", "value must be standard base64 (A–Z a–z 0–9 + /, padded)");
+    }
+    return new Uint8Array(Buffer.from(base64, "base64"));
+}
+/** Keys are UTF-8 text without NUL (the entry id uses "\0" as its separator). */
+exports.MAX_KEY_BYTES = 1024;
+function checkKey(key) {
+    if (typeof key !== "string" || key.length === 0) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", "key must be a non-empty string");
+    }
+    if (key.includes("\0")) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", "key must not contain a NUL character");
+    }
+    if (Buffer.byteLength(key, "utf8") > exports.MAX_KEY_BYTES) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", `key is longer than ${exports.MAX_KEY_BYTES} bytes`);
+    }
+    return key;
+}
+function checkAccessPolicy(policy) {
+    const p = policy;
+    if (!p || typeof p !== "object") {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", "accessPolicy must be an object");
+    }
+    if (!(0, types_js_1.isAccessScope)(p.readScope)) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", `unknown readScope '${String(p.readScope)}'`);
+    }
+    if (!(0, types_js_1.isAccessScope)(p.writeScope)) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", `unknown writeScope '${String(p.writeScope)}'`);
+    }
+    if (!(0, types_js_1.isSharePolicy)(p.sharePolicy)) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", `unknown sharePolicy '${String(p.sharePolicy)}'`);
+    }
+    return { readScope: p.readScope, writeScope: p.writeScope, sharePolicy: p.sharePolicy };
+}
+/** A retentionPolicy is at most 4 KiB of JSON. */
+/** Spec §30.2 `Int`: maxRetentionDays is 1..2147483647. */
+exports.MAX_RETENTION_DAYS = 2147483647;
+const RETENTION_FIELDS = ["maxRetentionDays", "autoDeleteOnTermination", "anonymizationSupported"];
+function checkRetentionPolicy(policy) {
+    if (policy === null || policy === undefined)
+        return null;
+    const unknown = typeof policy === "object" ? Object.keys(policy).filter((k) => !RETENTION_FIELDS.includes(k)) : [];
+    if (unknown.length > 0) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", `unknown retentionPolicy field(s) ${unknown.join(", ")}`);
+    }
+    const p = policy;
+    const days = p.maxRetentionDays;
+    if (typeof p !== "object" ||
+        !(days === null || (Number.isInteger(days) && days >= 1 && days <= exports.MAX_RETENTION_DAYS)) ||
+        typeof p.autoDeleteOnTermination !== "boolean" ||
+        typeof p.anonymizationSupported !== "boolean") {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", `retentionPolicy must be {maxRetentionDays: integer 1..${exports.MAX_RETENTION_DAYS} | null, autoDeleteOnTermination: boolean, anonymizationSupported: boolean} or null`);
+    }
+    return {
+        maxRetentionDays: days,
+        autoDeleteOnTermination: p.autoDeleteOnTermination,
+        anonymizationSupported: p.anonymizationSupported,
+    };
+}
+/** RFC 3339 UTC, as timestamps go on the wire. */
+function toTimestamp(ms) {
+    return new Date(ms).toISOString();
+}
+// RFC 3339 date-time: full date, full time, seconds, optional fraction, and
+// an explicit offset ("Z" or ±hh:mm). Date.parse alone accepts "2026" and
+// rolls "2026-02-30" over into March.
+const RFC3339 = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+function parseTimestamp(value, field) {
+    const bad = () => new types_js_1.MemoryError("MEMORY_INVALID_INPUT", `${field} must be an RFC 3339 timestamp, e.g. 2026-10-30T12:00:00Z`);
+    const m = typeof value === "string" ? RFC3339.exec(value) : null;
+    if (!m)
+        throw bad();
+    const [year, month, day, hour, minute, second] = m.slice(1, 7).map(Number);
+    const daysInMonth = new Date(Date.UTC(year, month, 0)).getUTCDate();
+    if (month < 1 || month > 12 || day < 1 || day > daysInMonth || hour > 23 || minute > 59 || second > 59)
+        throw bad();
+    const ms = Date.parse(value);
+    if (Number.isNaN(ms))
+        throw bad();
+    return ms;
+}
+function toEntryJson(entry) {
+    return { ...entry, value: encodeValue(entry.value) };
+}
+/** Parse an entry received over JSON; refuses anything outside the wire format. */
+function fromEntryJson(json) {
+    const j = json;
+    if (!j || typeof j !== "object")
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", "entry must be an object");
+    if (!(0, types_js_1.isMemoryCategory)(j.category)) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", `unknown category '${String(j.category)}'`);
+    }
+    if (typeof j.entryId !== "string" || !/^[0-9a-f]{64}$/.test(j.entryId)) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", "entryId must be 64 lowercase hex characters");
+    }
+    if (typeof j.createdBy !== "string" || j.createdBy.length === 0) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", "createdBy must be a gene id");
+    }
+    parseTimestamp(j.createdAt, "createdAt");
+    parseTimestamp(j.updatedAt, "updatedAt");
+    return {
+        entryId: j.entryId,
+        category: j.category,
+        key: checkKey(j.key),
+        value: decodeValue(j.value),
+        createdBy: j.createdBy,
+        lastAccessedBy: typeof j.lastAccessedBy === "string" ? j.lastAccessedBy : null,
+        createdAt: j.createdAt,
+        updatedAt: j.updatedAt,
+        accessPolicy: checkAccessPolicy(j.accessPolicy),
+        retentionPolicy: checkRetentionPolicy(j.retentionPolicy),
+    };
+}
+const QUOTA_UNITS = { KB: 1024, MB: 1024 ** 2, GB: 1024 ** 3 };
+/**
+ * `--memory-quota`: a positive number with a KB / MB /
+ * GB suffix (binary units, case-insensitive), e.g. `512KB`, `10MB`, `1.5GB`.
+ * Zero, negative and unit-less values are refused rather than guessed.
+ */
+function parseMemoryQuota(input) {
+    const match = /^\s*(-?\d+(?:\.\d+)?)\s*(KB|MB|GB)\s*$/i.exec(input);
+    if (!match) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", `memory quota '${input}' is not a size; use a number with KB, MB or GB, e.g. 10MB`);
+    }
+    const bytes = Math.floor(Number(match[1]) * QUOTA_UNITS[match[2].toUpperCase()]);
+    if (!(bytes > 0)) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", `memory quota must be greater than zero (got '${input}')`);
+    }
+    // Past 2^53 a JS number stops counting bytes exactly; the store (u64)
+    // would get a different quota from the one asked for.
+    if (!Number.isSafeInteger(bytes)) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", `memory quota '${input}' is too large`);
+    }
+    return bytes;
+}
+/**
+ * What the quota counts: the UTF-8 bytes of the key and the
+ * value's bytes — never JS string length. The retentionPolicy is bounded by
+ * its §30.2 schema and not counted.
+ */
+function entrySize(key, value) {
+    return Buffer.byteLength(key, "utf8") + value.byteLength;
+}
+/** A gene id as a caller's must be: "v2:" and 64 lowercase hex digits. */
+function isV2GeneId(id) {
+    return typeof id === "string" && /^v2:[0-9a-f]{64}$/.test(id);
+}
+//# sourceMappingURL=codec.js.map

package/dist/memory/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/memory/codec.ts"],"names":[],"mappings":";;;AAkBA,gCAEC;AAOD,kCAEC;AAED,kCAKC;AAKD,4BAWC;AAED,8CAeC;AAOD,oDAwBC;AAGD,kCAEC;AAOD,wCAUC;AAED,kCAEC;AAGD,sCA0BC;AASD,4CAkBC;AAOD,8BAEC;AAGD,gCAEC;AApMD;;;;GAIG;AACH,6CAAyC;AACzC,yCASoB;AAEpB,4EAA4E;AAC5E,SAAgB,UAAU,CAAC,OAAe,EAAE,GAAW;IACrD,OAAO,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,KAAK,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACjF,CAAC;AAED,wDAAwD;AACxD,4EAA4E;AAC5E,wDAAwD;AACxD,MAAM,MAAM,GAAG,kEAAkE,CAAC;AAElF,SAAgB,WAAW,CAAC,KAAiB;IAC3C,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC1F,CAAC;AAED,SAAgB,WAAW,CAAC,MAAe;IACzC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,yDAAyD,CAAC,CAAC;IAC3G,CAAC;IACD,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,iFAAiF;AACpE,QAAA,aAAa,GAAG,IAAI,CAAC;AAElC,SAAgB,QAAQ,CAAC,GAAY;IACnC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,gCAAgC,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,sCAAsC,CAAC,CAAC;IACxF,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,qBAAa,EAAE,CAAC;QACnD,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,sBAAsB,qBAAa,QAAQ,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAgB,iBAAiB,CAAC,MAAe;IAC/C,MAAM,CAAC,GAAG,MAA4C,CAAC;IACvD,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,gCAAgC,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,CAAC,IAAA,wBAAa,EAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,sBAAsB,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,CAAC,IAAA,wBAAa,EAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,uBAAuB,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,CAAC,IAAA,wBAAa,EAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,wBAAwB,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AAC1F,CAAC;AAED,kDAAkD;AAClD,2DAA2D;AAC9C,QAAA,kBAAkB,GAAG,UAAU,CAAC;AAC7C,MAAM,gBAAgB,GAAG,CAAC,kBAAkB,EAAE,yBAAyB,EAAE,wBAAwB,CAAC,CAAC;AAEnG,SAAgB,oBAAoB,CAAC,MAAe;IAClD,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACzD,MAAM,OAAO,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAgB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7H,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,oCAAoC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1G,CAAC;IACD,MAAM,CAAC,GAAG,MAAkC,CAAC;IAC7C,MAAM,IAAI,GAAG,CAAC,CAAC,gBAAgB,CAAC;IAChC,IACE,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAK,IAAe,IAAI,CAAC,IAAK,IAAe,IAAI,0BAAkB,CAAC,CAAC;QAC/G,OAAO,CAAC,CAAC,uBAAuB,KAAK,SAAS;QAC9C,OAAO,CAAC,CAAC,sBAAsB,KAAK,SAAS,EAC7C,CAAC;QACD,MAAM,IAAI,sBAAW,CACnB,sBAAsB,EACtB,yDAAyD,0BAAkB,qFAAqF,CACjK,CAAC;IACJ,CAAC;IACD,OAAO;QACL,gBAAgB,EAAE,IAAqB;QACvC,uBAAuB,EAAE,CAAC,CAAC,uBAAuB;QAClD,sBAAsB,EAAE,CAAC,CAAC,sBAAsB;KACjD,CAAC;AACJ,CAAC;AAED,kDAAkD;AAClD,SAAgB,WAAW,CAAC,EAAU;IACpC,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AACpC,CAAC;AAED,4EAA4E;AAC5E,0EAA0E;AAC1E,sCAAsC;AACtC,MAAM,OAAO,GAAG,oFAAoF,CAAC;AAErG,SAAgB,cAAc,CAAC,KAAc,EAAE,KAAa;IAC1D,MAAM,GAAG,GAAG,GAAG,EAAE,CAAC,IAAI,sBAAW,CAAC,sBAAsB,EAAE,GAAG,KAAK,2DAA2D,CAAC,CAAC;IAC/H,MAAM,CAAC,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACjE,IAAI,CAAC,CAAC;QAAE,MAAM,GAAG,EAAE,CAAC;IACpB,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3E,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;IACpE,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,EAAE,IAAI,GAAG,GAAG,CAAC,IAAI,GAAG,GAAG,WAAW,IAAI,IAAI,GAAG,EAAE,IAAI,MAAM,GAAG,EAAE,IAAI,MAAM,GAAG,EAAE;QAAE,MAAM,GAAG,EAAE,CAAC;IACpH,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAe,CAAC,CAAC;IACvC,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAAE,MAAM,GAAG,EAAE,CAAC;IAClC,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAgB,WAAW,CAAC,KAAkB;IAC5C,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;AACvD,CAAC;AAED,mFAAmF;AACnF,SAAgB,aAAa,CAAC,IAAa;IACzC,MAAM,CAAC,GAAG,IAAuC,CAAC;IAClD,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,yBAAyB,CAAC,CAAC;IAC1G,IAAI,CAAC,IAAA,2BAAgB,EAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,qBAAqB,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC5F,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QACvE,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,6CAA6C,CAAC,CAAC;IAC/F,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,6BAA6B,CAAC,CAAC;IAC/E,CAAC;IACD,cAAc,CAAC,CAAC,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACzC,cAAc,CAAC,CAAC,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACzC,OAAO;QACL,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC;QACpB,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC;QAC3B,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,cAAc,EAAE,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI;QAC9E,SAAS,EAAE,CAAC,CAAC,SAAmB;QAChC,SAAS,EAAE,CAAC,CAAC,SAAmB;QAChC,YAAY,EAAE,iBAAiB,CAAC,CAAC,CAAC,YAAY,CAAC;QAC/C,eAAe,EAAE,oBAAoB,CAAC,CAAC,CAAC,eAAe,CAAC;KACzD,CAAC;AACJ,CAAC;AAED,MAAM,WAAW,GAA2B,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;AAEvF;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,KAAa;IAC5C,MAAM,KAAK,GAAG,yCAAyC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,sBAAW,CACnB,sBAAsB,EACtB,iBAAiB,KAAK,4DAA4D,CACnF,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IACjF,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;QACjB,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,gDAAgD,KAAK,IAAI,CAAC,CAAC;IAC3G,CAAC;IACD,sEAAsE;IACtE,sDAAsD;IACtD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,iBAAiB,KAAK,gBAAgB,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAgB,SAAS,CAAC,GAAW,EAAE,KAAiB;IACtD,OAAO,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC;AAC3D,CAAC;AAED,0EAA0E;AAC1E,SAAgB,UAAU,CAAC,EAAW;IACpC,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAChE,CAAC"}

package/dist/memory/data-policy.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Spec §30.2 DataPolicy, and what it allows a gene to write into AgentMemory
+ * (spec §38.2 "与数据主权的集成").
+ *
+ * §30.2 has no field that says "may not write memory", so the checks below
+ * are what the declared policy implies for a memory entry:
+ *   1. an entry may not be kept longer than the agent's data retention;
+ *   2. an entry may not be shareable (ANONYMIZED_SHARE / KNOWLEDGE_GENE)
+ *      when the agent's data cannot be anonymised — §38.3 makes
+ *      de-identification a MUST before anything leaves as a knowledge gene;
+ *   3. DEPLOYER_CONFIGURED resolves from the DataPolicy, which defines no
+ *      memory scope (always "not configured", so denied; no
+ *      field is invented for it).
+ * A violation is MEMORY_ACCESS_DENIED.
+ */
+import type { MemoryAccessPolicy, RetentionPolicy } from "./types.js";
+export type DataOwner = "DEPLOYER" | "USER" | "AGENT" | {
+    SHARED: string[];
+};
+export interface DataPolicy {
+    inputDataOwnership: DataOwner;
+    outputDataOwnership: DataOwner;
+    learningDataOwnership: DataOwner;
+    metadataOwnership: DataOwner;
+    retentionPolicy: RetentionPolicy;
+    deletionSupport: boolean;
+}
+/**
+ * What `rotifer agent create` records when the deployer configures nothing
+ * (§30.2 says the deployer MUST configure one; this is the explicit
+ * default written into the agent record, not an implied one). Learning data
+ * — which memory is — belongs to the agent and travels with it (§30.4);
+ * retention has no day limit; and nothing claims anonymisation it does not
+ * do, so shareable entries are refused until the deployer says otherwise.
+ */
+export declare const DEFAULT_DATA_POLICY: Readonly<DataPolicy>;
+/** Why a write breaks the agent's DataPolicy, or null if it does not. */
+export declare function dataPolicyViolation(policy: DataPolicy, accessPolicy: MemoryAccessPolicy, retention: RetentionPolicy | null): string | null;
+//# sourceMappingURL=data-policy.d.ts.map

package/dist/memory/data-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-policy.d.ts","sourceRoot":"","sources":["../../src/memory/data-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEtE,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE7E,MAAM,WAAW,UAAU;IACzB,kBAAkB,EAAE,SAAS,CAAC;IAC9B,mBAAmB,EAAE,SAAS,CAAC;IAC/B,qBAAqB,EAAE,SAAS,CAAC;IACjC,iBAAiB,EAAE,SAAS,CAAC;IAC7B,eAAe,EAAE,eAAe,CAAC;IACjC,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,UAAU,CAWrC,CAAC;AAEjB,yEAAyE;AACzE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,kBAAkB,EAChC,SAAS,EAAE,eAAe,GAAG,IAAI,GAChC,MAAM,GAAG,IAAI,CAgBf"}

package/dist/memory/data-policy.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DATA_POLICY = void 0;
+exports.dataPolicyViolation = dataPolicyViolation;
+/**
+ * What `rotifer agent create` records when the deployer configures nothing
+ * (§30.2 says the deployer MUST configure one; this is the explicit
+ * default written into the agent record, not an implied one). Learning data
+ * — which memory is — belongs to the agent and travels with it (§30.4);
+ * retention has no day limit; and nothing claims anonymisation it does not
+ * do, so shareable entries are refused until the deployer says otherwise.
+ */
+exports.DEFAULT_DATA_POLICY = Object.freeze({
+    inputDataOwnership: "DEPLOYER",
+    outputDataOwnership: "DEPLOYER",
+    learningDataOwnership: "AGENT",
+    metadataOwnership: "DEPLOYER",
+    retentionPolicy: Object.freeze({
+        maxRetentionDays: null,
+        autoDeleteOnTermination: false,
+        anonymizationSupported: false,
+    }),
+    deletionSupport: true,
+});
+/** Why a write breaks the agent's DataPolicy, or null if it does not. */
+function dataPolicyViolation(policy, accessPolicy, retention) {
+    const agentDays = policy.retentionPolicy.maxRetentionDays;
+    if (retention && agentDays !== null) {
+        if (retention.maxRetentionDays === null || retention.maxRetentionDays > agentDays) {
+            return `retentionPolicy keeps the entry ${retention.maxRetentionDays ?? "indefinitely"} day(s); the agent's DataPolicy allows at most ${agentDays}`;
+        }
+    }
+    if (accessPolicy.sharePolicy !== "PRIVATE" && !policy.retentionPolicy.anonymizationSupported) {
+        return `sharePolicy ${accessPolicy.sharePolicy} needs a DataPolicy that supports anonymisation (§38.3); this agent's does not`;
+    }
+    const isDeployerScopeUsed = accessPolicy.readScope === "DEPLOYER_CONFIGURED" || accessPolicy.writeScope === "DEPLOYER_CONFIGURED";
+    if (isDeployerScopeUsed) {
+        return "DEPLOYER_CONFIGURED resolves from the agent's DataPolicy (§30.2), which defines no memory scope yet, so it is treated as not configured";
+    }
+    return null;
+}
+//# sourceMappingURL=data-policy.js.map

package/dist/memory/data-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-policy.js","sourceRoot":"","sources":["../../src/memory/data-policy.ts"],"names":[],"mappings":";;;AAkDA,kDAoBC;AA1CD;;;;;;;GAOG;AACU,QAAA,mBAAmB,GAAyB,MAAM,CAAC,MAAM,CAAC;IACrE,kBAAkB,EAAE,UAAU;IAC9B,mBAAmB,EAAE,UAAU;IAC/B,qBAAqB,EAAE,OAAO;IAC9B,iBAAiB,EAAE,UAAU;IAC7B,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC;QAC7B,gBAAgB,EAAE,IAAI;QACtB,uBAAuB,EAAE,KAAK;QAC9B,sBAAsB,EAAE,KAAK;KAC9B,CAAC;IACF,eAAe,EAAE,IAAI;CACtB,CAAe,CAAC;AAEjB,yEAAyE;AACzE,SAAgB,mBAAmB,CACjC,MAAkB,EAClB,YAAgC,EAChC,SAAiC;IAEjC,MAAM,SAAS,GAAG,MAAM,CAAC,eAAe,CAAC,gBAAgB,CAAC;IAC1D,IAAI,SAAS,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACpC,IAAI,SAAS,CAAC,gBAAgB,KAAK,IAAI,IAAI,SAAS,CAAC,gBAAgB,GAAG,SAAS,EAAE,CAAC;YAClF,OAAO,mCAAmC,SAAS,CAAC,gBAAgB,IAAI,cAAc,kDAAkD,SAAS,EAAE,CAAC;QACtJ,CAAC;IACH,CAAC;IACD,IAAI,YAAY,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,sBAAsB,EAAE,CAAC;QAC7F,OAAO,eAAe,YAAY,CAAC,WAAW,gFAAgF,CAAC;IACjI,CAAC;IACD,MAAM,mBAAmB,GACvB,YAAY,CAAC,SAAS,KAAK,qBAAqB,IAAI,YAAY,CAAC,UAAU,KAAK,qBAAqB,CAAC;IACxG,IAAI,mBAAmB,EAAE,CAAC;QACxB,OAAO,yIAAyI,CAAC;IACnJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/memory/host.d.ts

@@ -0,0 +1,119 @@
+import { type NativeBinding } from "../utils/binding.js";
+import { type GeneMemoryAccess } from "./access.js";
+import { type MemoryAuditSink } from "./audit.js";
+import { type MemoryBackend, type NativeMemoryApi } from "./backend.js";
+import { type DataPolicy } from "./data-policy.js";
+import { type MemoryTelemetrySink } from "./telemetry.js";
+/** The memory fields of an agent record (`.rotifer/agents/<id>.json`). */
+export interface AgentMemoryFields {
+    id: string;
+    /** Bytes; absent on agents created before v0.9.4 → the 10 MB default. */
+    memoryQuota?: number;
+    /** §30.2; absent on agents created before v0.9.4 → DEFAULT_DATA_POLICY. */
+    dataPolicy?: DataPolicy;
+}
+export declare function memoryQuotaOf(agent: AgentMemoryFields): number;
+/**
+ * The calling gene's content-derived id (the v0.9.1 v2 id).
+ * There is no fallback: an entry's `createdBy` is what CREATOR_GENE_ONLY
+ * compares, and a second id scheme would make the same gene two creators.
+ */
+export declare function geneIdentity(genesRoot: string, geneName: string): string;
+/**
+ * rotifer-napi's memory, on a PlaygroundBinding opened on the project
+ * (store: `<root>/.rotifer/playground.db`), or null when the loaded addon has
+ * no memory functions. tryLoadBinding() opens its own instance under the
+ * user's home for other purposes; memory belongs to the project, so this
+ * opens another instance of the same class on the project root.
+ */
+export declare function projectNativeMemory(root: string): (NativeMemoryApi & NativeBinding) | null;
+/**
+ * What the WASM path needs for a gene's memory calls: a binding
+ * opened on the project — the one tryLoadBinding() returns lives under the
+ * user's home, and its store is not the agent's — and the memoryContext JSON
+ * rotifer-napi takes.
+ */
+export interface WasmMemory {
+    binding: NativeBinding;
+    /** For executeGene: {"agentId","geneId"}; a gene without a v2 id gets {"agentId"} alone, and its calls are denied. */
+    geneContext(geneName: string): string;
+    /** For executeAlgebra: {"agentId"}; each gene runs as its entry's v2Id. */
+    agentContext: string;
+}
+/**
+ * Make sure the agent's memory exists in the native store, with its quota
+ * (`agent create`, and first use by an agent created before v0.9.4).
+ * Returns false when there is no native store to create it in.
+ */
+export declare function ensureAgentMemory(native: NativeMemoryApi | null, agent: AgentMemoryFields): boolean;
+export interface OpenGeneMemoryOptions {
+    /** Project root (where `.rotifer/` lives). */
+    root: string;
+    agent: AgentMemoryFields;
+    gene: {
+        id: string;
+        domain: string;
+    };
+    /** The store. Omitted → rotifer-napi's on this project, or none (memoryUnavailable). */
+    backend?: MemoryBackend;
+    telemetry?: MemoryTelemetrySink;
+    audit?: MemoryAuditSink;
+}
+/** A GeneMemoryAccess for `gene` inside `agent`. */
+export declare function openGeneMemory(options: OpenGeneMemoryOptions): GeneMemoryAccess;
+export interface AgentMemoryHandle {
+    /** "napi" (rotifer-core's store) or "unavailable" (no native memory: every call fails). */
+    store: "napi" | "unavailable";
+    /** The WASM path's binding and memoryContext; null without native memory, or when the store cannot execute genes. */
+    wasm: WasmMemory | null;
+    /** GeneMemoryAccess for one gene of the agent. Never undefined: a gene it cannot identify gets one that refuses, saying why. */
+    forGene(geneName: string, phenotype: {
+        domain?: unknown;
+    }): GeneMemoryAccess;
+    /** The same, for a host that already holds the caller's v2 gene id and domain. */
+    forCaller(geneId: string, domain: string): GeneMemoryAccess;
+}
+/**
+ * An agent's memory for one `agent run` (spec §38.2; Node path ctx.memory),
+ * in rotifer-napi's store on this project — created there on first use with
+ * the agent's quota. Without native memory every call fails with
+ * MEMORY_STORAGE_ERROR. Tests pass `native` to pin the store.
+ */
+export declare function openAgentMemory(options: {
+    root: string;
+    genesRoot: string;
+    agent: AgentMemoryFields;
+    native?: NativeMemoryApi | null;
+    telemetry?: MemoryTelemetrySink;
+    audit?: MemoryAuditSink;
+}): AgentMemoryHandle;
+/**
+ * A throwaway agent memory for `rotifer test`, so a gene author can test a
+ * gene that uses memory: rotifer-napi's store in a fresh directory under the
+ * system temp dir, for a one-off agent with the default quota — as ctx.memory
+ * for the Node path, and as a binding + memoryContext for the WASM path.
+ * `dispose()` removes the directory. Without native memory every call is
+ * MEMORY_STORAGE_ERROR, as anywhere else.
+ */
+export declare function scratchGeneMemory(options: {
+    genesRoot: string;
+    geneName: string;
+    phenotype: {
+        domain?: unknown;
+    };
+    /** Tests pin the store; omitted → rotifer-napi's, if the addon has memory. */
+    openNative?: (dir: string) => NativeMemoryApi | null;
+}): {
+    memory: GeneMemoryAccess;
+    wasm: WasmMemory | null;
+    dispose(): void;
+};
+/**
+ * `rotifer run`'s memory for the gene in `geneDir`: no agent, so every call
+ * is refused "no agent context", and each refusal is reported to the
+ * project's .rotifer/telemetry.jsonl (honouring ROTIFER_TELEMETRY / DO_NOT_TRACK)
+ * with agentId null and the gene's v2 id when it has one — the record
+ * rotifer-core makes for a WASM gene run the same way.
+ */
+export declare function projectNoAgentMemory(root: string, geneDir: string): GeneMemoryAccess;
+//# sourceMappingURL=host.d.ts.map

package/dist/memory/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/memory/host.ts"],"names":[],"mappings":"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"}

package/dist/memory/host.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memoryQuotaOf = memoryQuotaOf;
+exports.geneIdentity = geneIdentity;
+exports.projectNativeMemory = projectNativeMemory;
+exports.ensureAgentMemory = ensureAgentMemory;
+exports.openGeneMemory = openGeneMemory;
+exports.openAgentMemory = openAgentMemory;
+exports.scratchGeneMemory = scratchGeneMemory;
+exports.projectNoAgentMemory = projectNoAgentMemory;
+/**
+ * The CLI's side of AgentMemory (spec §38.2): opening an agent's memory in
+ * rotifer-napi's store and binding it to one gene, for the Node path
+ * (ctx.memory) and the WASM path (a binding + memoryContext).
+ *
+ * Memory belongs to the agent (§38.1): it is keyed by the agent id, and
+ * nothing here looks at the agent's genome, so replacing genes neither
+ * deletes nor rewrites it.
+ *
+ * The store is rotifer-napi's, in the project's `.rotifer/playground.db`
+ *. Without the native binding there is no memory: every call
+ * fails with MEMORY_STORAGE_ERROR "native binding unavailable". There is no
+ * fallback store.
+ *
+ * Not part of `@rotifer/playground/memory`: these signatures carry the
+ * native binding's types.
+ */
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const binding_js_1 = require("../utils/binding.js");
+const access_js_1 = require("./access.js");
+const audit_js_1 = require("./audit.js");
+const backend_js_1 = require("./backend.js");
+const data_policy_js_1 = require("./data-policy.js");
+const telemetry_js_1 = require("./telemetry.js");
+const types_js_1 = require("./types.js");
+const index_js_1 = require("./index.js");
+function memoryQuotaOf(agent) {
+    return agent.memoryQuota ?? types_js_1.DEFAULT_MEMORY_QUOTA_BYTES;
+}
+/**
+ * The calling gene's content-derived id (the v0.9.1 v2 id).
+ * There is no fallback: an entry's `createdBy` is what CREATOR_GENE_ONLY
+ * compares, and a second id scheme would make the same gene two creators.
+ */
+function geneIdentity(genesRoot, geneName) {
+    const result = (0, binding_js_1.geneIdV2)(genesRoot, geneName);
+    if ("reason" in result) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", `gene '${geneName}' has no content-derived id, so it cannot use agent memory: ${result.reason}`);
+    }
+    return result.id;
+}
+/**
+ * rotifer-napi's memory, on a PlaygroundBinding opened on the project
+ * (store: `<root>/.rotifer/playground.db`), or null when the loaded addon has
+ * no memory functions. tryLoadBinding() opens its own instance under the
+ * user's home for other purposes; memory belongs to the project, so this
+ * opens another instance of the same class on the project root.
+ */
+function projectNativeMemory(root) {
+    const loaded = (0, binding_js_1.tryLoadBinding)();
+    if (!loaded || !(0, backend_js_1.hasNativeMemory)(loaded) || typeof loaded.constructor !== "function")
+        return null;
+    const binding = new loaded.constructor(root);
+    return (0, backend_js_1.hasNativeMemory)(binding) ? binding : null;
+}
+/**
+ * Make sure the agent's memory exists in the native store, with its quota
+ * (`agent create`, and first use by an agent created before v0.9.4).
+ * Returns false when there is no native store to create it in.
+ */
+function ensureAgentMemory(native, agent) {
+    if (!native)
+        return false;
+    try {
+        native.memoryGet(agent.id);
+    }
+    catch (err) {
+        const e = (0, backend_js_1.asMemoryError)(err);
+        if (e.code !== "MEMORY_NOT_FOUND")
+            throw e;
+        try {
+            native.memoryCreate(agent.id, memoryQuotaOf(agent));
+            // Entries with no retentionPolicy of their own inherit the agent's
+            // DataPolicy retention; unlimited needs no call.
+            const days = agent.dataPolicy?.retentionPolicy.maxRetentionDays ?? null;
+            if (days !== null)
+                native.memorySetDataPolicyRetention(agent.id, days);
+        }
+        catch (createErr) {
+            throw (0, backend_js_1.asMemoryError)(createErr);
+        }
+    }
+    return true;
+}
+/** A GeneMemoryAccess for `gene` inside `agent`. */
+function openGeneMemory(options) {
+    const { root, agent, gene } = options;
+    let backend = options.backend;
+    if (!backend) {
+        const native = projectNativeMemory(root);
+        if (!native)
+            return (0, index_js_1.memoryUnavailable)();
+        ensureAgentMemory(native, agent);
+        backend = new backend_js_1.NapiMemoryBackend(native);
+    }
+    return (0, access_js_1.createGeneMemoryAccess)({
+        backend,
+        caller: { agentId: agent.id, geneId: gene.id, domain: gene.domain },
+        dataPolicy: agent.dataPolicy ?? data_policy_js_1.DEFAULT_DATA_POLICY,
+        telemetry: options.telemetry ?? (0, telemetry_js_1.fileTelemetrySink)(root),
+        audit: options.audit ?? (0, audit_js_1.fileAuditSink)(root),
+    });
+}
+/**
+ * An agent's memory for one `agent run` (spec §38.2; Node path ctx.memory),
+ * in rotifer-napi's store on this project — created there on first use with
+ * the agent's quota. Without native memory every call fails with
+ * MEMORY_STORAGE_ERROR. Tests pass `native` to pin the store.
+ */
+function openAgentMemory(options) {
+    const { root, genesRoot, agent } = options;
+    const native = options.native === undefined ? projectNativeMemory(root) : options.native;
+    ensureAgentMemory(native, agent);
+    const backend = native ? new backend_js_1.NapiMemoryBackend(native) : null;
+    const forCaller = (geneId, domain) => backend
+        ? openGeneMemory({ root, agent, gene: { id: geneId, domain }, backend, telemetry: options.telemetry, audit: options.audit })
+        : (0, index_js_1.memoryUnavailable)();
+    const canExecute = native !== null && typeof native.executeGene === "function";
+    return {
+        store: backend ? "napi" : "unavailable",
+        wasm: canExecute
+            ? {
+                binding: native,
+                geneContext(geneName) {
+                    const id = (0, binding_js_1.geneIdV2)(genesRoot, geneName);
+                    return JSON.stringify("id" in id ? { agentId: agent.id, geneId: id.id } : { agentId: agent.id });
+                },
+                agentContext: JSON.stringify({ agentId: agent.id }),
+            }
+            : null,
+        forGene(geneName, phenotype) {
+            if (!backend)
+                return (0, index_js_1.memoryUnavailable)();
+            const domain = typeof phenotype.domain === "string" ? phenotype.domain : "";
+            let geneId;
+            try {
+                geneId = geneIdentity(genesRoot, geneName);
+            }
+            catch (err) {
+                // The store refuses a caller without a v2 id and records it (audit,
+                // geneId null, and §17), as rotifer-core does
+                // for WASM genes; the refusal tells the author why.
+                return explainRefusals(forCaller("", domain), `gene '${geneName}' cannot use agent memory: ${err.message}`);
+            }
+            return forCaller(geneId, domain);
+        },
+        forCaller,
+    };
+}
+/**
+ * A throwaway agent memory for `rotifer test`, so a gene author can test a
+ * gene that uses memory: rotifer-napi's store in a fresh directory under the
+ * system temp dir, for a one-off agent with the default quota — as ctx.memory
+ * for the Node path, and as a binding + memoryContext for the WASM path.
+ * `dispose()` removes the directory. Without native memory every call is
+ * MEMORY_STORAGE_ERROR, as anywhere else.
+ */
+function scratchGeneMemory(options) {
+    const dir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "rotifer-test-memory-"));
+    const dispose = () => {
+        try {
+            (0, node_fs_1.rmSync)(dir, { recursive: true, force: true, maxRetries: 3 });
+        }
+        catch {
+            /* a temp dir; the OS cleans what an open handle kept */
+        }
+    };
+    try {
+        const native = (options.openNative ?? projectNativeMemory)(dir);
+        if (!native) {
+            dispose();
+            return { memory: (0, index_js_1.memoryUnavailable)(), wasm: null, dispose: () => { } };
+        }
+        const agent = { id: `test-${(0, node_crypto_1.randomUUID)()}` };
+        const handle = openAgentMemory({ root: dir, genesRoot: options.genesRoot, agent, native });
+        return { memory: handle.forGene(options.geneName, options.phenotype), wasm: handle.wasm, dispose };
+    }
+    catch (err) {
+        dispose();
+        throw err;
+    }
+}
+/** `memory`, whose MEMORY_ACCESS_DENIED refusals carry `why` instead of the store's generic message. */
+function explainRefusals(memory, why) {
+    const explain = (call) => {
+        try {
+            return call();
+        }
+        catch (err) {
+            if (err instanceof types_js_1.MemoryError && err.code === "MEMORY_ACCESS_DENIED")
+                throw new types_js_1.MemoryError("MEMORY_ACCESS_DENIED", why);
+            throw err;
+        }
+    };
+    return {
+        readMemory: (...args) => explain(() => memory.readMemory(...args)),
+        writeMemory: (...args) => explain(() => memory.writeMemory(...args)),
+        queryMemory: (...args) => explain(() => memory.queryMemory(...args)),
+        deleteMemory: (...args) => explain(() => memory.deleteMemory(...args)),
+    };
+}
+/**
+ * `rotifer run`'s memory for the gene in `geneDir`: no agent, so every call
+ * is refused "no agent context", and each refusal is reported to the
+ * project's .rotifer/telemetry.jsonl (honouring ROTIFER_TELEMETRY / DO_NOT_TRACK)
+ * with agentId null and the gene's v2 id when it has one — the record
+ * rotifer-core makes for a WASM gene run the same way.
+ */
+function projectNoAgentMemory(root, geneDir) {
+    const id = (0, binding_js_1.geneIdV2)((0, node_path_1.dirname)(geneDir), (0, node_path_1.basename)(geneDir));
+    return (0, index_js_1.noAgentMemory)({ telemetry: (0, telemetry_js_1.fileTelemetrySink)(root), geneId: "id" in id ? id.id : null });
+}
+//# sourceMappingURL=host.js.map

package/dist/memory/host.js.map

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