Deep Dive: The Deterministic Sandbox

In a traditional framework, testing against a database or an API is a dangerous, stateful operation. You have to set up test databases, manage environment variables, and write complex teardown scripts to ensure one test doesn't pollute the next.

When an AI is writing the code, the danger multiplies. You cannot simply eval() untrusted, AI-generated logic against your local database.

To solve this, Carotene executes every test block inside the Deterministic Sandbox—an ephemeral, highly restricted runtime environment designed specifically to contain and evaluate AI-generated code safely.

Because different tests require different levels of realism, Carotene provides granular control over the sandbox engine directly inside the test block.

1. The Dual-Engine Database Sandbox

You don't need to build fake database drivers, but you also shouldn't be forced to wait for Docker containers for simple math tests. Carotene gives you two native sandbox engines to balance speed and reality.

Engine A: The Embedded DB (Default)

By default, Carotene compiles a WebAssembly (WASM) version of your database (e.g., PGLite or embedded SQLite) directly into the runtime memory of the test runner.

• The Speed: Because it runs entirely in RAM without virtualization, a test executes in roughly 2ms.
• The Safety: It evaluates actual, real SQL and respects constraints, but evaporates the millisecond the test finishes.

Engine B: The Transactional Docker DB

If a specific test requires a heavy, real-world database feature that an embedded engine cannot handle (like a complex Postgres GIS spatial extension), you can upgrade the sandbox.

• Carotene spins up a single, persistent Docker container in the background during carrot build.
• For the test, the sandbox opens a database transaction (BEGIN), injects your mock data, runs the AI's function, asserts the results, and then instantly runs ROLLBACK. The database is wiped clean for the next test without restarting the container.

The config Block

You control exactly which engine is used on a per-test basis using the native config block.

domain Commerce {
  
  // Test 1: Simple math. Use the blazing fast embedded engine.
  test "Calculates standard refund" {
    config { sandbox: PostgresEmbedded }
    
    given customer = mock store.Customer { id: "cust_1", loyaltyTier: "Standard" }
    // ...
  }

  // Test 2: Needs real Postgres extensions. Upgrade the sandbox.
  test "Calculates delivery distance via spatial query" {
    config { sandbox: DockerTransactional }
    
    given location = mock store.Location { lat: 40.7128, lng: -74.0060 }
    // ...
  }
}

2. The Network Guillotine (Physical Disconnection)

The Carotene sandbox does not just simulate databases; it physically severs network access.

When the AI compiles the code for your @(...) Generative Operator, the sandbox denies all outbound HTTP, TCP, and UDP traffic. The only way the code can communicate with the outside world is through the explicit integration boundaries you defined in your architecture.

• Forced Interception: If your function includes calls integration.Stripe, the sandbox intercepts the exact moment the AI attempts to fire that request.
• Strict Enforcement: If you provided a mocks integration.Stripe -> true statement in your test, the sandbox instantly returns true. If you forgot to mock the integration, the sandbox immediately kills the test with a Sandbox Violation Error rather than letting a rogue network request slip out to the real internet.

3. Sandboxed Time and Randomness

A true architectural blueprint must be mathematically deterministic. If a test passes once, it must pass 100% of the time.

However, AI models occasionally generate logic using Date.now() or Math.random(). In traditional testing, this causes "flaky tests" that randomly fail in your CI/CD pipeline.

The Carotene Sandbox automatically controls these environmental variables:

• Frozen Time: Inside the sandbox, the system clock is paused at a static timestamp. If you need to test time-based logic, you can explicitly fast-forward sandbox time using standard test configuration (e.g., config { time: "2026-01-01" }).
• Seeded Randomness: Any calls to random number generators are automatically seeded, ensuring the AI's logic produces the exact same output on your local machine as it does on a remote server.

4. The Autonomic Feedback Loop

The Sandbox is not just a protective measure; it is the engine that drives Test-Driven Generation (TDG).

Because you have granular control over the sandbox weight, Carotene can run a continuous, autonomic loop at blazing speeds:

1. The LLM generates the initial code.
2. The Sandbox evaluates the code against your test constraints.
3. If an asserts statement fails, the Sandbox captures the exact state of memory, the stack trace, and the failed value.
4. The Sandbox feeds this deterministic proof directly back to the LLM.
5. The LLM refines the code, and the Sandbox tests it again.

By the time you see the green Build Successful message in your terminal, the AI and the Sandbox have already negotiated, debated, and perfected the implementation in milliseconds, entirely out of sight.