el/tools/neuron-sandbox/STACK.md

# sandbox — the Neuron STACK sandbox

**Work on a whole stack at once, not one repo at a time.** `sandbox` assembles every
constituent repo of a named stack into **one combined worktree workspace**, wired so
they build and run **together**, on an isolated clean base — then tears it all down
cleanly. The live soul/engram (`:7770` / `:8742`) are never touched.

It is the multi-repo sibling of [`nsbx`](./README.md): where `nsbx dev` stands up
**one** repo's worktree + an isolated engram, `sandbox` stands up **every** repo of a
stack as sibling git worktrees under a single workspace.

```bash
export PATH="$PWD:$PATH"            # or symlink `sandbox` onto your PATH

sandbox neuron-stack tim           # el + neuron soul + NeuronUI, assembled together
cd ~/Development/neuron-technologies/stack-worktrees/neuron-stack-tim
source .stack-env                  # EL_REPO + PATH now point at the SANDBOX el
./build.sh                         # engram compiles, soul compiles, UI present & buildable
sandbox down neuron-stack tim      # remove every worktree; live untouched
```

## The two profiles

### `el-stack` — the whole EL kit
The compiler + language + framework + tooling are **all one repo** (`foundation/el`:
`lang/` = elc/elb + runtime, `engram/src/server.el`, `elp/` = NLG, `ui/` = the **el-ui
framework**, plus `ql`, `ide`, `epm`, `arbor`, `tools`). Its downstream SDK consumers
come along so a change to `elc` can be proven end-to-end across the kit.

| repo | required | role |
|------|----------|------|
| `foundation/el`     | ✓ | elc + elb compiler, el_runtime, engram source, **el-ui framework**, elp/ql/ide/epm tooling |
| `engram-language`   |   | language-faculty reference POC (Python) — being ported into `el/elp` |
| `foundation/forge`  |   | downstream SDK consumer — `make build` |
| `foundation/dharma` |   | downstream SDK consumer — CGI provenance registry |

`build.sh` proves it: `elc` compiles a real stack source and `cc` links it against the
runtime into a native binary (elc + runtime build together), and — if present — `forge`
builds against the freshly-assembled SDK.

### `neuron-stack` — the full product
Substrate + soul + UI. **Engram is not a separate repo** — its source lives inside
`foundation/el`.

| repo | required | role |
|------|----------|------|
| `foundation/el`     | ✓ | substrate: elc + el_runtime + engram source + the `elp` NLG the soul imports |
| `neuron`            | ✓ | the soul (`:7770`) + engram build; `soul.el` imports `../foundation/el/elp/src/elp.el` |
| `products/NeuronUI` | ✓ | the app/UI (Kotlin/Compose desktop client; bundles the soul binary) |
| `products/web`      |   | marketing site + interactive soul-demo |

`build.sh` proves it: **engram** builds (`elc engram/src/server.el` → `cc … el_runtime.c`
→ native binary), the **soul** compiles with its cross-repo `../foundation/el` import
resolving to the *sandbox* el, and the **UI** is present with its build entry.

## Why it works — mirrored-layout wiring

The repos reference each other by **relative sibling paths** (e.g. the soul imports
`../foundation/el/elp/src/elp.el`). So `sandbox` lays every worktree out at its **natural
relative path** inside the workspace:

```
stack-worktrees/neuron-stack-tim/
├── foundation/el/          ← worktree of foundation/el   (the sandbox el)
├── neuron/                 ← worktree of neuron
└── products/NeuronUI/      ← worktree of products/NeuronUI
```

From `neuron/`, `../foundation/el` resolves to `…/neuron-stack-tim/foundation/el` — the
**sandbox** copy, never the live tree. No symlinks, no path rewriting: the layout *is*
the wiring. `.stack-env` additionally pins `EL_REPO` and prepends the sandbox `elc`/`elb`
to `PATH`.

## Commands

| command | does |
|---------|------|
| `sandbox el-stack <name> [--minimal]`     | assemble the EL kit (`--minimal` = required repos only) |
| `sandbox neuron-stack <name> [--minimal]` | assemble the full product |
| `sandbox build <profile> <name>`          | run the workspace's combined `build.sh` |
| `sandbox status <profile> <name>`         | per-repo head + clean/dirty |
| `sandbox list`                            | list assembled workspaces |
| `sandbox down <profile> <name> [--delete-branch]` | remove every worktree + drop the workspace (branch kept unless `--delete-branch`) |

Flags: `--minimal` (required repos only), `--branch B` (branch name; default
`sandbox/<profile>-<name>`), `--base REF` (fork point; default each repo's committed
HEAD).

## Rails (always)

- **Clean base** — worktrees fork off each repo's **committed HEAD**; the dirty state of
  the live checkout is deliberately *not* carried in.
- **Persistent** — the workspace lives under `NSBX_STACK_ROOT` (default
  `~/Development/neuron-technologies/stack-worktrees`), **never `/tmp`** (ablated on
  compaction).
- **Never touches live** — `sandbox` only does `git worktree` + offline `cc`. It never
  binds `:8742`/`:7770`, never `launchctl`, never `pkill`. Bringing up an **isolated
  engram** is delegated, opt-in, to `nsbx` (which guards the live store and refuses the
  live ports).
- **Idempotent & safe** — refuses to clobber an existing workspace; a failed assembly
  rolls back its partial worktrees; teardown removes worktrees through their origin repo
  and prunes.
- **Own-the-core** — pure bash + `git worktree`. No new dependencies.

## Env knobs

`NSBX_STACK_ROOT` (workspace root), `NEURON_DEV_ROOT` (the dir holding all the peer
repos, default `~/Development/neuron-technologies`).

## Isolated engram for `neuron-stack` (opt-in)

`sandbox` gets the code building together; to run the soul against an **isolated** engram
(never live), delegate to `nsbx` from inside the workspace:

```bash
source .stack-env
nsbx create $STACK_NAME --source "$EL_REPO"    # clone live store onto a non-default port
nsbx up     $STACK_NAME
nsbx status $STACK_NAME                          # prints the isolated engram URL
```