@rotifer/playground 0.31.0 → 0.33.0

package/dist/commands/agent-memory.js

@@ -0,0 +1,235 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentMemoryCommand = void 0;
+exports.listAgentMemory = listAgentMemory;
+exports.creatorLabels = creatorLabels;
+exports.deleteSelector = deleteSelector;
+exports.deleteAgentMemory = deleteAgentMemory;
+/**
+ * `rotifer agent memory` — the deployer's view of an agent's memory
+ *. PREFERENCE entries are never evicted
+ * for quota, so a full memory needs a person to look and clean up.
+ *
+ * `list` shows what is stored without the values: key, category, size,
+ * the creating gene and the last update. Values can hold user data (§30), so
+ * they are never printed. `delete` removes one key or a whole category
+ * through rotifer-napi's deployer path (memoryAdminDelete), which audits each
+ * entry with actor "deployer". Both work on rotifer-napi's store in the
+ * project (`.rotifer/playground.db`); the deployer owns the agent, so gene
+ * access scopes do not apply. There is no edit command.
+ */
+const commander_1 = require("commander");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const display = __importStar(require("../utils/display.js"));
+const config_js_1 = require("../utils/config.js");
+const binding_js_1 = require("../utils/binding.js");
+const project_root_js_1 = require("../utils/project-root.js");
+const agent_run_js_1 = require("./agent-run.js");
+const agent_create_js_1 = require("./agent-create.js");
+const index_js_1 = require("../memory/index.js");
+const host_js_1 = require("../memory/host.js");
+const codec_js_1 = require("../memory/codec.js");
+const types_js_1 = require("../memory/types.js");
+/**
+ * What `agent memory list` shows. An agent created before v0.9.4 has no
+ * memory yet: an empty listing, not an error. Without native memory there is
+ * no store to read: MEMORY_STORAGE_ERROR.
+ */
+function listAgentMemory(native, agentId, category) {
+    if (!native) {
+        throw new types_js_1.MemoryError("MEMORY_STORAGE_ERROR", "native binding unavailable: agent memory needs the rotifer native addon on this platform");
+    }
+    let memory;
+    try {
+        memory = native.memoryGet(agentId);
+    }
+    catch (err) {
+        const e = (0, index_js_1.asMemoryError)(err);
+        if (e.code === "MEMORY_NOT_FOUND")
+            return { entries: [], totalSize: 0, quota: null };
+        throw e;
+    }
+    const entries = memory.entries
+        .filter((e) => category === undefined || e.category === category)
+        .map((e) => ({
+        key: e.key,
+        category: e.category,
+        size: (0, codec_js_1.entrySize)(e.key, Buffer.from(e.value, "base64")),
+        createdBy: e.createdBy,
+        updatedAt: e.updatedAt,
+    }))
+        .sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : a.key < b.key ? -1 : 1));
+    return { entries, totalSize: memory.totalSize, quota: memory.quota };
+}
+/**
+ * How a creating gene is shown: its name when a gene in the project has that
+ * id, otherwise (an older version, a gene since removed) a short id prefix.
+ */
+function creatorLabels(genesRoot) {
+    const names = new Map();
+    if ((0, node_fs_1.existsSync)(genesRoot)) {
+        for (const name of (0, node_fs_1.readdirSync)(genesRoot)) {
+            const result = (0, binding_js_1.geneIdV2)(genesRoot, name);
+            if ("id" in result)
+                names.set(result.id, name);
+        }
+    }
+    return (geneId) => names.get(geneId) ?? `${geneId.slice(0, 15)}…`;
+}
+/**
+ * The selector from `--key` / `--category`: exactly one of them. A bad one
+ * is MEMORY_INVALID_INPUT, before anything is touched.
+ */
+function deleteSelector(options) {
+    const hasKey = options.key !== undefined;
+    const hasCategory = options.category !== undefined;
+    if (hasKey === hasCategory) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", "give exactly one of --key or --category");
+    }
+    if (hasKey) {
+        if (options.key === "")
+            throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", "--key must not be empty");
+        return { key: options.key };
+    }
+    if (!(0, types_js_1.isMemoryCategory)(options.category)) {
+        throw new types_js_1.MemoryError("MEMORY_INVALID_INPUT", `unknown memory category '${options.category}'; use one of PREFERENCE, PATTERN, CONTEXT, CACHE`);
+    }
+    return { category: options.category };
+}
+/** Delete as the deployer; returns how many entries went. A missing key is MEMORY_NOT_FOUND. */
+function deleteAgentMemory(native, agentId, selector) {
+    if (!native || typeof native.memoryAdminDelete !== "function") {
+        throw new types_js_1.MemoryError("MEMORY_STORAGE_ERROR", "native binding unavailable: agent memory needs the rotifer native addon on this platform");
+    }
+    try {
+        return Number(native.memoryAdminDelete(agentId, JSON.stringify(selector)));
+    }
+    catch (err) {
+        throw (0, index_js_1.asMemoryError)(err);
+    }
+}
+/** The agent named on the command line, or exit with E0050. */
+function agentOrExit(root, agentName) {
+    const agent = (0, agent_run_js_1.findAgent)(root, agentName);
+    if (!agent) {
+        display.rustStyleError({
+            code: "E0050",
+            message: `Agent '${agentName}' not found`,
+            suggestion: "List agents: rotifer agent list",
+        });
+        process.exit(1);
+    }
+    return agent;
+}
+const memoryListCommand = new commander_1.Command("list")
+    .description("List an agent's memory entries: key, category, size, creating gene, last update (values are not shown)")
+    .argument("<agent-name>", "agent name")
+    .option("-c, --category <category>", "only this category: PREFERENCE, PATTERN, CONTEXT or CACHE")
+    .addHelpText("after", ["", "Examples:", "  $ rotifer agent memory list my-agent", "  $ rotifer agent memory list my-agent --category PREFERENCE"].join("\n"))
+    .action((agentName, options) => {
+    const root = (0, project_root_js_1.requireProjectRoot)();
+    const agent = agentOrExit(root, agentName);
+    if (options.category !== undefined && !(0, types_js_1.isMemoryCategory)(options.category)) {
+        display.rustStyleError({
+            code: "E0040",
+            message: `unknown memory category '${options.category}'`,
+            suggestion: "Use one of PREFERENCE, PATTERN, CONTEXT, CACHE",
+        });
+        process.exit(1);
+    }
+    let listing;
+    try {
+        listing = listAgentMemory((0, host_js_1.projectNativeMemory)(root), agent.id, options.category);
+    }
+    catch (err) {
+        const e = (0, index_js_1.asMemoryError)(err);
+        display.rustStyleError({ code: "E0040", message: `${e.code}: ${e.message}` });
+        process.exit(1);
+    }
+    display.header(`Agent Memory: ${agentName}`);
+    const creator = creatorLabels((0, node_path_1.join)(root, (0, config_js_1.loadConfig)(root).genes_dir));
+    if (listing.entries.length === 0) {
+        display.info(options.category ? `No ${options.category} entries` : "No memory entries yet");
+    }
+    else {
+        display.table(listing.entries.map((e) => ({ ...e, createdBy: creator(e.createdBy) })), [
+            { key: "key", label: "Key" },
+            { key: "category", label: "Category", width: 12 },
+            { key: "size", label: "Size", align: "right", format: (v) => (0, agent_create_js_1.formatQuota)(Number(v)) },
+            { key: "createdBy", label: "Created by" },
+            { key: "updatedAt", label: "Updated" },
+        ]);
+    }
+    const quota = listing.quota === null ? "no memory created yet" : `${(0, agent_create_js_1.formatQuota)(listing.totalSize)} of ${(0, agent_create_js_1.formatQuota)(listing.quota)} used`;
+    display.hint(`${listing.entries.length} entr${listing.entries.length === 1 ? "y" : "ies"} shown · ${quota}`);
+});
+const memoryDeleteCommand = new commander_1.Command("delete")
+    .description("Delete an agent's memory entries as the deployer: one key, or every entry of one category")
+    .argument("<agent-name>", "agent name")
+    .option("-k, --key <key>", "the entry with this key")
+    .option("-c, --category <category>", "every entry of this category: PREFERENCE, PATTERN, CONTEXT or CACHE")
+    .addHelpText("after", [
+    "",
+    "Give exactly one of --key or --category. PREFERENCE entries are never evicted for quota, so this is how a full memory is cleared.",
+    "",
+    "Examples:",
+    "  $ rotifer agent memory delete my-agent --key preference-demo/ada/language",
+    "  $ rotifer agent memory delete my-agent --category CACHE",
+].join("\n"))
+    .action((agentName, options) => {
+    const root = (0, project_root_js_1.requireProjectRoot)();
+    const agent = agentOrExit(root, agentName);
+    let deleted;
+    try {
+        deleted = deleteAgentMemory((0, host_js_1.projectNativeMemory)(root), agent.id, deleteSelector(options));
+    }
+    catch (err) {
+        const e = (0, index_js_1.asMemoryError)(err);
+        display.rustStyleError({
+            code: "E0040",
+            message: `${e.code}: ${e.message}`,
+            suggestion: e.code === "MEMORY_NOT_FOUND" ? `See what is stored: rotifer agent memory list ${agentName}` : undefined,
+        });
+        process.exit(1);
+    }
+    display.success(`Deleted ${deleted} entr${deleted === 1 ? "y" : "ies"} from ${agentName}'s memory`);
+});
+exports.agentMemoryCommand = new commander_1.Command("memory")
+    .description("Look at and clean up an agent's memory (deployer tools)")
+    .addCommand(memoryListCommand)
+    .addCommand(memoryDeleteCommand);
+//# sourceMappingURL=agent-memory.js.map

package/dist/commands/agent-memory.js.map

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

package/dist/commands/agent-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-run.d.ts","sourceRoot":"","sources":["../../src/commands/agent-run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBpC,UAAU,SAAS;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,OAAO,CAAC;YAAC,MAAM,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;QAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,eAAO,MAAM,eAAe,SA8WxB,CAAC;AAudL,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAgB3E;AAUD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,IAAI,CA0DN"}
+{"version":3,"file":"agent-run.d.ts","sourceRoot":"","sources":["../../src/commands/agent-run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBpC,UAAU,SAAS;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,OAAO,CAAC;YAAC,MAAM,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;QAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,eAAO,MAAM,eAAe,SAiZxB,CAAC;AA4fL,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAgB3E;AAUD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,IAAI,CA0DN"}

package/dist/commands/agent-run.js

@@ -48,6 +48,7 @@ const project_root_js_1 = require("../utils/project-root.js");
 const binding_js_1 = require("../utils/binding.js");
 const l0_gate_js_1 = require("../utils/l0-gate.js");
 const network_gateway_js_1 = require("../runtime/network-gateway.js");
+const host_js_1 = require("../memory/host.js");
 const domain_failover_js_1 = require("../runtime/domain-failover.js");
 const invocation_js_1 = require("../cloud/invocation.js");
 const heartbeat_js_1 = require("../telemetry/heartbeat.js");
@@ -106,16 +107,42 @@ exports.agentRunCommand = new commander_1.Command("run")
     const l0Binding = (0, binding_js_1.tryLoadBinding)();
     const binding = isSandboxEnabled ? l0Binding : null;
     const startTime = performance.now();
+    // The agent's memory for this run (spec §38.2): ctx.memory on the Node
+    // path, and the project binding + memoryContext on the WASM path.
+    const agentMemory = (0, host_js_1.openAgentMemory)({ root, genesRoot: genesDir, agent });
     // TryPool: domain-based failover with fitness tracking
     if (compositionType === "TryPool") {
-        await executeTryPool(agent, genesDir, binding, l0Binding, input, root, options.verbose, options.trustUnsigned);
+        await executeTryPool(agent, genesDir, binding, l0Binding, input, root, options.verbose, options.trustUnsigned, agentMemory);
         return;
     }
-    // For non-Seq compositions with WASM support, use executeAlgebra()
-    if (compositionType !== "Single" && compositionType !== "Seq" && binding) {
-        const algebra = executeViaAlgebra(agent, genesDir, binding, input, compositionType, options.verbose);
+    // Par, Cond and Try run only on the Rust algebra executor, which needs the
+    // sandbox and every gene compiled. Where it cannot run, the agent is
+    // refused before any gene executes: the sequential loop below would run
+    // a different workflow under the same label — Seq's result for Par and
+    // Cond, a Try that never reaches its handler, a branch that should not
+    // have run (#450).
+    if (compositionType !== "Single" && compositionType !== "Seq") {
+        const refuse = (reason, hint) => {
+            display.error(`${compositionType} cannot run here: ${reason}. No gene was run.`);
+            display.hint(hint);
+            process.exit(1);
+        };
+        if (!binding) {
+            if (!isSandboxEnabled) {
+                refuse("--no-sandbox runs genes as Node.js modules one after another, which is Seq, not " + compositionType, "Run it without --no-sandbox, or create a Seq agent for the Node.js path.");
+            }
+            else {
+                refuse("it runs on the sandbox's algebra executor, and the native addon did not load", "Run 'rotifer doctor' to see what is missing.");
+            }
+            return;
+        }
+        const algebra = executeViaAlgebra(agent, genesDir, binding, input, compositionType, options.verbose, agentMemory.wasm);
         if (algebra.kind === "failed")
             return;
+        if (algebra.kind === "unavailable") {
+            refuse(algebra.reason, algebra.hint);
+            return;
+        }
         if (algebra.kind === "done") {
             const totalElapsed = performance.now() - startTime;
             console.log();
@@ -128,10 +155,9 @@ exports.agentRunCommand = new commander_1.Command("run")
             console.log(JSON.stringify(algebra.output, null, 2));
             return;
         }
-        display.warn("Falling back to sequential execution (some genes not compiled)");
     }
     const pipelineLog = [];
-    // Sequential execution (Seq / Single / fallback)
+    // Sequential execution (Seq / Single)
     let current = input;
     for (let i = 0; i < agent.genome.length; i++) {
         const geneName = agent.genome[i];
@@ -150,7 +176,9 @@ exports.agentRunCommand = new commander_1.Command("run")
                     ? JSON.parse((0, node_fs_1.readFileSync)(phenotypePath, "utf-8"))
                     : {};
                 const { irHash: _strip, ...phenotypeForExec } = rawPhenotype;
-                const result = binding.executeGene(irWasm, JSON.stringify(current), JSON.stringify(phenotypeForExec), sandbox_defaults_js_1.DEFAULT_SANDBOX_CONSTRAINTS_JSON);
+                // With native memory, run on the project binding so the gene's
+                // memory calls reach the agent's store.
+                const result = (agentMemory.wasm?.binding ?? binding).executeGene(irWasm, JSON.stringify(current), JSON.stringify(phenotypeForExec), sandbox_defaults_js_1.DEFAULT_SANDBOX_CONSTRAINTS_JSON, agentMemory.wasm?.geneContext(geneName));
                 const stepElapsed = performance.now() - stepStart;
                 if (result.success) {
                     display.success(`${step} ${geneName} completed via WASM sandbox (${result.durationMs}ms, fuel: ${result.fuelConsumed})`);
@@ -296,17 +324,19 @@ exports.agentRunCommand = new commander_1.Command("run")
                     process.exit(1);
                 }
                 let result;
+                // The agent's memory (spec §38.2; ctx.memory), bound to this gene.
+                const memory = agentMemory.forGene(geneName, phenotypeData);
                 if (phenotypeData.fidelity === "Hybrid" && phenotypeData.network) {
                     const { gatewayFetch, gateway } = (0, network_gateway_js_1.createGatewayFetch)(phenotypeData.network);
                     display.info(`  ${geneName} is Hybrid — gateway active (domains: ${phenotypeData.network.allowedDomains?.join(", ") || "none"})`);
-                    result = await mod.express(current, { gatewayFetch });
+                    result = await mod.express(current, { gatewayFetch, memory });
                     if (options.verbose) {
                         const stats = gateway.stats;
                         display.info(`  Gateway stats: ${stats.totalRequests} requests, ${stats.totalBytes} bytes`);
                     }
                 }
                 else {
-                    result = await mod.express(current);
+                    result = await mod.express(current, { memory });
                 }
                 const stepElapsed = performance.now() - stepStart;
                 display.success(`${step} ${geneName} completed via Node.js (${stepElapsed.toFixed(1)}ms)`);
@@ -394,7 +424,7 @@ function printPipelineLog(log) {
         }
     }
 }
-async function executeTryPool(agent, genesDir, binding, l0Binding, input, root, isVerbose, isTrustUnsigned) {
+async function executeTryPool(agent, genesDir, binding, l0Binding, input, root, isVerbose, isTrustUnsigned, agentMemory) {
     const engine = new domain_failover_js_1.DomainFailoverEngine();
     const startTime = performance.now();
     for (const geneName of agent.genome) {
@@ -406,7 +436,7 @@ async function executeTryPool(agent, genesDir, binding, l0Binding, input, root,
         const domain = phenotype.domain || "default";
         const irWasmPath = (0, node_path_1.join)(geneDir, "gene.ir.wasm");
         const hasWasm = (0, node_fs_1.existsSync)(irWasmPath);
-        const executor = await buildGeneExecutor(geneName, geneDir, irWasmPath, hasWasm, phenotype, binding, l0Binding, isTrustUnsigned);
+        const executor = await buildGeneExecutor(geneName, geneDir, irWasmPath, hasWasm, phenotype, binding, l0Binding, isTrustUnsigned, agentMemory.forGene(geneName, phenotype), agentMemory.wasm);
         engine.registerGene(geneName, domain, executor);
     }
     const fitnessPath = (0, node_path_1.join)(root, ".rotifer", "agents", `${agent.name}.fitness.json`);
@@ -499,7 +529,11 @@ function refuseNodeExecution(geneDir, isTrustUnsigned) {
         return null;
     return "Cloud-installed genes cannot run via Node.js without sandbox.";
 }
-async function buildGeneExecutor(geneName, geneDir, irWasmPath, hasWasm, phenotype, binding, l0Binding, isTrustUnsigned) {
+async function buildGeneExecutor(geneName, geneDir, irWasmPath, hasWasm, phenotype, binding, l0Binding, isTrustUnsigned, 
+/** The agent's memory for this gene, handed to a Node-path gene as ctx.memory. */
+memory, 
+/** The same memory for the WASM path: project binding + memoryContext. */
+wasmMemory) {
     if (hasWasm && binding) {
         const wasmBytes = (0, node_fs_1.readFileSync)(irWasmPath);
         const { irHash: _strip, ...phenotypeForExec } = phenotype;
@@ -507,7 +541,7 @@ async function buildGeneExecutor(geneName, geneDir, irWasmPath, hasWasm, phenoty
         return async (input) => {
             const start = performance.now();
             try {
-                const result = binding.executeGene(wasmBytes, JSON.stringify(input), phenoStr, sandbox_defaults_js_1.DEFAULT_SANDBOX_CONSTRAINTS_JSON);
+                const result = (wasmMemory?.binding ?? binding).executeGene(wasmBytes, JSON.stringify(input), phenoStr, sandbox_defaults_js_1.DEFAULT_SANDBOX_CONSTRAINTS_JSON, wasmMemory?.geneContext(geneName));
                 const elapsed = performance.now() - start;
                 (0, run_logger_js_1.logGeneExecution)({ geneDir,
                     geneName, success: result.success, durationMs: elapsed,
@@ -592,10 +626,10 @@ async function buildGeneExecutor(geneName, geneDir, irWasmPath, hasWasm, phenoty
             let result;
             if (isHybrid) {
                 const { gatewayFetch } = (0, network_gateway_js_1.createGatewayFetch)(phenotype.network);
-                result = await mod.express(input, { gatewayFetch });
+                result = await mod.express(input, { gatewayFetch, memory });
             }
             else {
-                result = await mod.express(input);
+                result = await mod.express(input, { memory });
             }
             const elapsed = performance.now() - start;
             (0, run_logger_js_1.logGeneExecution)({ geneDir,
@@ -629,18 +663,28 @@ async function buildGeneExecutor(geneName, geneDir, irWasmPath, hasWasm, phenoty
 function geneNameToId(geneName) {
     return (0, node_crypto_1.createHash)("sha256").update(geneName).digest("hex");
 }
-function executeViaAlgebra(agent, genesDir, binding, input, compositionType, isVerbose) {
+function executeViaAlgebra(agent, genesDir, binding, input, compositionType, isVerbose, 
+/** With native memory: run on the project binding with {"agentId"}; each gene acts as its entry's v2Id. */
+wasmMemory) {
     const comp = agent.composition;
-    if (!comp)
-        return { kind: "fallback" };
+    if (!comp) {
+        return {
+            kind: "unavailable",
+            reason: "this agent has no composition record",
+            hint: `Re-create it: rotifer agent create ${agent.name} --genes ${agent.genome.join(" ")} --composition ${compositionType}`,
+        };
+    }
     const geneEntries = {};
     for (const geneName of agent.genome) {
         const geneDir = (0, node_path_1.join)(genesDir, geneName);
         const irWasmPath = (0, node_path_1.join)(geneDir, "gene.ir.wasm");
         const phenotypePath = (0, node_path_1.join)(geneDir, "phenotype.json");
         if (!(0, node_fs_1.existsSync)(irWasmPath)) {
-            display.warn(`  Gene '${geneName}' not compiled — cannot use ${compositionType} via Rust executor`);
-            return { kind: "fallback" };
+            return {
+                kind: "unavailable",
+                reason: `gene '${geneName}' is not compiled, and the algebra executor runs compiled genes only`,
+                hint: `Compile it first: rotifer compile ${geneName}`,
+            };
         }
         const wasmBytes = (0, node_fs_1.readFileSync)(irWasmPath);
         const phenotype = (0, node_fs_1.existsSync)(phenotypePath)
@@ -682,8 +726,13 @@ function executeViaAlgebra(agent, genesDir, binding, input, compositionType, isV
             break;
         }
         case "Cond": {
-            if (geneIds.length < 2)
-                return { kind: "fallback" };
+            if (geneIds.length < 2) {
+                return {
+                    kind: "unavailable",
+                    reason: `it needs two genes and this agent has ${geneIds.length}`,
+                    hint: "Re-create the agent with two genes.",
+                };
+            }
             const pred = comp?.predicate;
             algebraExpr = {
                 Cond: {
@@ -700,8 +749,13 @@ function executeViaAlgebra(agent, genesDir, binding, input, compositionType, isV
             break;
         }
         case "Try": {
-            if (geneIds.length < 2)
-                return { kind: "fallback" };
+            if (geneIds.length < 2) {
+                return {
+                    kind: "unavailable",
+                    reason: `it needs two genes and this agent has ${geneIds.length}`,
+                    hint: "Re-create the agent with two genes.",
+                };
+            }
             algebraExpr = {
                 Try: {
                     primary: { Gene: hexToGeneIdArray(geneIds[0]) },
@@ -712,14 +766,18 @@ function executeViaAlgebra(agent, genesDir, binding, input, compositionType, isV
             break;
         }
         default:
-            return { kind: "fallback" };
+            return {
+                kind: "unavailable",
+                reason: `'${compositionType}' is not a composition agent run knows`,
+                hint: "Use Seq, Par, Cond, Try or TryPool.",
+            };
     }
     try {
         // Same sandbox limits as the Single / Seq path (execute_gene). Without
         // them the binding falls back to ConstraintSet::default() (1M fuel),
         // below what one compiled gene of ordinary size needs. A binding older
         // than this argument ignores it.
-        const result = binding.executeAlgebra(JSON.stringify(algebraExpr), JSON.stringify(geneEntries), JSON.stringify(input), sandbox_defaults_js_1.DEFAULT_SANDBOX_CONSTRAINTS_JSON);
+        const result = (wasmMemory?.binding ?? binding).executeAlgebra(JSON.stringify(algebraExpr), JSON.stringify(geneEntries), JSON.stringify(input), sandbox_defaults_js_1.DEFAULT_SANDBOX_CONSTRAINTS_JSON, wasmMemory?.agentContext);
         if (result.success) {
             display.success(`${compositionType} execution completed (${result.totalDurationMs}ms, fuel: ${result.totalFuelConsumed})`);
             if (isVerbose) {