docs(emergent,sandbox): clarify sandbox memory-limit enforcement is nominal not preemptive

The node:vm-backed JavaScript executor reports heap deltas after
the fact; it does not preemptively terminate the process when the
nominal memoryMB budget is exceeded. Previous TSDoc on
SandboxExecutionRequest.memoryMB and SandboxExecutionResult.error
overstated the enforcement guarantee, which could mislead callers
into shipping untrusted code under the assumption that runaway
allocators would be killed.

Updated the type-level docs + tests + sandbox executor + the
EMERGENT_CAPABILITIES architecture page so the contract reads
honestly and the future-isolate-backed-runtime path is documented
as the route to preemptive enforcement.

Author: jddunn

docs/architecture/EMERGENT_CAPABILITIES.md

@@ -556,9 +556,9 @@ await importEmergentTool('./slugify.emergent-tool.yaml', { seedId: agentSeedId }
     maxSessionTools: 10,           // Max tools per session
     maxAgentTools: 50,             // Max persisted per agent
 
-    // Sandbox resource limits
+    // Sandbox resource limits and telemetry
     sandboxTimeoutMs: 5000,        // VM execution timeout
-    sandboxMemoryMB: 128,          // VM memory cap
+    sandboxMemoryMB: 128,          // Nominal budget; node:vm reports heap delta only
 
     // Judge configuration
     judgeModel: 'gpt-4o-mini',    // Model for creation reviews

src/emergent/SandboxedToolForge.ts

@@ -23,7 +23,7 @@ import type { SandboxExecutionRequest, SandboxAPI } from '../types.js';
 
 /**
  * Build a minimal {@link SandboxExecutionRequest} from just code and input.
- * Defaults: empty allowlist, 128 MB memory, 5000 ms timeout.
+ * Defaults: empty allowlist, 128 MB nominal memory budget, 5000 ms timeout.
  */
 function makeRequest(
   code: string,

src/emergent/__tests__/sandboxed-forge.spec.ts

@@ -335,7 +335,7 @@ describe('emergent/types', () => {
       expect(DEFAULT_EMERGENT_CONFIG.persistSandboxSource).toBe(false);
     });
 
-    it('has correct sandbox memory limit', () => {
+    it('has correct sandbox memory budget', () => {
       expect(DEFAULT_EMERGENT_CONFIG.sandboxMemoryMB).toBe(128);
     });
 

src/emergent/__tests__/types.spec.ts

@@ -185,8 +185,9 @@ export interface SandboxExecutionRequest {
   allowlist: SandboxAPI[];
 
   /**
-   * Maximum heap memory in megabytes the sandbox process may consume.
-   * The executor terminates the process if this limit is exceeded.
+   * Nominal heap budget in megabytes for the sandbox execution.
+   * The current node:vm-backed JavaScript executor reports heap deltas but does
+   * not preemptively enforce this limit.
    * @default 128
    */
   memoryMB: number;
@@ -215,7 +216,8 @@ export interface SandboxExecutionResult {
 
   /**
    * Human-readable error description, present when `success` is `false`.
-   * Includes timeout, memory-exceeded, and thrown-exception cases.
+   * Includes timeout and thrown-exception cases. A future isolate-backed
+   * runtime may also report memory-exceeded cases.
    */
   error?: string;
 
@@ -226,7 +228,7 @@ export interface SandboxExecutionResult {
   executionTimeMs: number;
 
   /**
-   * Peak heap memory used by the sandbox process in bytes.
+   * Observed heap delta for the sandbox execution in bytes.
    * Populated when the runtime can measure it; otherwise `0`.
    */
   memoryUsedBytes: number;
@@ -688,7 +690,9 @@ export interface EmergentConfig {
   persistSandboxSource: boolean;
 
   /**
-   * Memory limit in megabytes for each sandboxed tool execution.
+   * Nominal memory budget in megabytes for each sandboxed tool execution.
+   * The current node:vm-backed executor reports heap deltas but does not
+   * preemptively enforce this limit.
    * Passed as `SandboxExecutionRequest.memoryMB`.
    * @default 128
    */

src/emergent/types.ts

@@ -39,7 +39,7 @@ import {
 
 const DEFAULT_CONFIG: SandboxConfig = {
   timeoutMs: 30000, // 30 seconds
-  maxMemoryBytes: 128 * 1024 * 1024, // 128MB
+  maxMemoryBytes: 128 * 1024 * 1024, // Nominal budget; JS node:vm reports heap delta only.
   maxOutputBytes: 1024 * 1024, // 1MB
   allowNetwork: false,
   allowFilesystem: false,
@@ -748,4 +748,3 @@ export class CodeSandbox implements ICodeSandbox {
     return 'low';
   }
 }
-