# Intent-Based Scripting Languages

**Track:** `intent_dsl_survey_20260612` (initialized 2026-06-12)
**Date:** 2026-06-12
**Location:** `conductor/tracks/intent_dsl_survey_20260612/report.md` (this file; moved from `docs/ideation/` per user instruction — the report is too closely related to the track to live in the general ideation folder)
**Author:** Tier 1 Orchestrator (sections 1, 3, 4, 5, 6, 7, Appendix); Tier 2 sub-agents (section 2 clusters 0-4, with research sub-reports at `research/cluster_*.md`)
**Status:** Draft for self-review (phase 3 of 4)

> **What this is.** A survey of intent-based scripting languages as a design philosophy, plus a proposed vocabulary (~40 verbs across 4 tiers) for a Meta-Tooling-facing intent DSL. The report is the foundation document for the user's nagent v2.2 (its "Future-Track Candidate #4" section) and for the future interpreter prototype (follow-up B track).
>
> **What this is NOT.** Not an interpreter, not a bridge script, not Application-side function-calling, not XML/JSON record formats. The DSL is Meta-Tooling-side per `docs/guide_meta_boundary.md` — the format external agents (Gemini CLI, OpenCode) emit when invoking `mcp_client.py` tools. The Application's provider-native function-calling stays unchanged.

---

## 1. The "Intent-Based" Design Philosophy

The DSL is grounded in four anchor claims. Each claim has a philosophical home and a specific design consequence for the vocab and grammar.

### 1.1 Claim 1 — Intent-based means the user's words are declarative intent, not imperative commands

Jofito (per its 2026 README update) calls itself an **"intent mapping engine"**: the user writes declarative intent (e.g., "find all pictures, filter out JPEGs, print the list"), and Jofito decomposes that intent into platform-optimal operations. From the Jofito README: *"jofito is a 'write the optimization once, reap the benefits everywhere' system that takes what the user wants to accomplish (intent) as input and decomposes it into operations that make the most sense for the current system."* (`https://codeberg.org/jbruchon/jofito`)

The canonical Jofito example is `list = scandir("/path/here/", {filter !extension=jpg,jpeg}) : print(list)` — a single declarative expression that replaces `find . -type f | grep -v jpg | grep -v jpeg`. The DSL inherits this framing: the verbs in §4 are **intent verbs** (e.g., `scan` for "I want to read a source", `filter` for "I want to keep only what matches", `audit` for "I want to record what happened"), not imperative primitives.

This is the *philosophical* anchor for the DSL: the user says *what they want*; the verbs are the way to say it; the bridge script and the MCP tools handle *how to do it*. The user's own math pseudocode (the `determinate`/`minor`/`matrix-transpose` snippets shared during spec review) operates at this declarative level — "here is the math, the verbs are the words."

### 1.2 Claim 2 — The hardware is the truth

The verbs must map to actual hardware/software stages, not abstract commands. The Onat/Lottes 2-register model (per `C:\projects\forth\bootslop\references\kyra_in-depth.md` and `X.com - Onat & Lottes Interaction 1.png.ocr.md`) gives the concrete hardware the DSL is mapped to:

- **2-register stack (RAX/RDX)**: the DSL's `->` chain *maps* to RAX-passed data. Each verb in the chain is a "word" in Onat's sense (no args, no returns — the X.com thread at `X.com - Onat & Lottes Interaction 1.png.ocr.md:80-86` quotes Lottes: "I laugh when people say C is like assembly, they were missing what we did in assembly back then, which was all registers and globals and gotos, no stacks").
- **Magenta pipe `|` (KYRA) → our `->`**: same definition-boundary semantics, retargeted to data flow.
- **Basic blocks `[ ]` (KYRA) → our `[ ]`**: compilation units; the parser produces a `[ ]` block per `->`-delimited stage.
- **Lambdas `{ }` (KYRA) → our `arena { }`**: arena-scoped blocks; the contents are pre-scattered into tape-drive regions (per the X.com thread at line 55-61, where Onat describes Lottes's "common arguments pushed onto the tape using store duplication when they are known... so it's preemptive scatter, so later at call time there is no argument gather").

The verbs are not arbitrary. Each Tier 2 verb (data pipeline) and Tier 3 verb (shell) has a direct hardware mapping; this is what makes the verbs *fast* on the targeted hardware.

### 1.3 Claim 3 — The pipeline is immediate-mode

Per John O'Donnell's IMGUI essay (`https://johno.se/book/imgui.html`): *"Widgets, logically, change from being objects to being method invocations."* The pipeline `scan -> filter -> print` is not a Pipeline object with state; it is a sequence of method calls. Once execution ends, the pipeline's state is gone. The next invocation is independent.

This is the *paradigm* anchor for the DSL. It means:
- The parser doesn't need to track pipeline state across executions; each invocation is independent.
- The `->` chain has no "pipeline object" you can query, name, or pass around. The only way to "name" a chain is to wrap it in a function (`determinate(m, row) -> Scalar { ... }`).
- Verbs exist *only* when called. There is no implicit verb inventory. (This is why the DSL's "Everything" mode in the Command Palette is implementable as a search across *text*, not across a *registry of pipeline objects*.)

O'Donnell's MVC essay (`https://johno.se/book/mvc.html`) extends this: *"Writes to Model are formalized through the addition of IEventTarget. This is a pure virtual interface that defines all possible state changes / events on a system wide level."* The DSL's `sandbox` verb is the IEventTarget boundary; the `audit` verb is the IEventTarget itself (see §6 Claim 9 and Claim 10).

### 1.4 Claim 4 — The vocabulary IS the user surface

CoSy (per `https://cosy.com/CoSy/Simplicity.html`): *"CoSy is a TimeStamped notebook/log created as an open vocabulary in Forth."* And: *"an extensive vocabulary evolved from APL via K, mainly slicing and dicing, searching & replacing, and applying verbs to each item in lists."*

For the DSL, the **vocabulary** is the user surface — not the syntax, not the parser, not the runtime. For AI agents that emit the DSL, the vocab is the API. A model that knows the 40 verbs in §4 and the 14 grammar primitives in §3 can express any intent that the DSL supports. There is no separate "API documentation" — the verbs ARE the API.

This is why the report devotes so much space to the vocab (§4) and so little to the syntax (§3). The syntax is trivial (RPN with a few delimiters); the vocabulary is the substance.

### 1.5 The four claims together

The four claims are not independent; they compose:

- Claim 1 (intent-mapping) → the user expresses what they want; the verbs are the vocabulary.
- Claim 2 (hardware is the truth) → the verbs map to real data-oriented pipeline stages.
- Claim 3 (immediate-mode) → the verbs are method calls, not stateful objects; pipelines have no persistent state.
- Claim 4 (vocabulary is the user surface) → the 40-verb vocab is the API; the syntax is trivial.

The composition is: a user expresses intent (Claim 1) using a verb (Claim 4) that maps to a hardware stage (Claim 2) in a single per-frame composition (Claim 3). The full report is a working-out of this composition.

---

## 2. Prior Art Survey (8 Clusters)

This section surveys the design lineage across 8 clusters. Each cluster: a "cluster claim" (what the DSL inherits from the cluster as a whole), then 1 sentence per entry, then specific "take" bullets that §3, §4, §5, and §6 reference.

The detailed analysis for each cluster lives in the research sub-reports at `research/cluster_*.md` (relative to this file). This section is the executive summary; the sub-reports are the evidence.

### Cluster 0 — Immediate-Mode Paradigm (philosophical anchor)

**Cluster claim.** The DSL's *paradigm* — verbs as method calls, no persistent state, reads free, writes formalized — is the direct application of John O'Donnell's IMGUI/MVC framework to a Meta-Tooling context. (Per the full sub-report at `research/cluster_0_odonnell.md`.)

**Entry: John O'Donnell — IMGUI / The Pitch / MVC / IM-MVC roadmap.** `https://johno.se/book/imgui.html`, `https://johno.se/book/pitch.html`, `https://johno.se/book/immvc.html`, `https://johno.se/book/mvc.html`. Four interconnected pages laying out a unified paradigm: visualization is not inherently stateful; widgets are method invocations not objects; the "reads are free, writes are formalized" invariant via a single IEventTarget interface; the View must not expose scene-graph abstractions.

**Take bullets (referenced by §5, §6):**
- *Anchor Claim 3 (IEventTarget as single event interface for all state changes):* *"Experience dictates that there only be a single IEventTarget interface that is responsible for all 'system events'."* — `mvc.html`, "Why only a single event interface" section.
- *Anchor Claim 4 (View must not expose scene-graph abstractions):* *"The corresponding interface should be of the form: `view::drawMesh(mesh, transform, anyOtherRenderState);`"* — `mvc.html`, "View" section.
- *"Writes to Model are formalized through the addition of IEventTarget. This is a pure virtual interface that defines all possible state changes / events on a system wide level."* — `mvc.html`, "Writing to Model state" section.
- *"What is a non-stateful view? Basically it is a procedural interface (as opposed to a collection of objects with methods), in essence very much to what DirectX 9 is."* — `pitch.html`, "MVC revisited" section.
- *"However, due to the rapide advances of GPU based rendering over the past 10+ years, this premise no longer holds."* — `pitch.html`, "However!" section.
- The 800,000-vertex single-draw-call empirical result at Jungle Peak (GeForce 6 hardware) — `pitch.html`, batch rendering section.

### Cluster 1 — Concatenative (Forth family)

**Cluster claim.** The DSL's *syntax* — postfix RPN, stack-passed arguments, no AST object — is the Forth tradition as refined by Onat Türkçüoğlu's KYRA (2-register stack, magenta pipe as definition boundary, basic blocks and lambdas, preemptive scatter) and Timothy Lottes's x68/5th (32-bit instruction granularity, annotation overlay, "register file as aliased global namespace"). Bob Armstrong's CoSy is the user's-vocabulary-as-the-surface model. (Per the full sub-report at `research/cluster_1_concatenative.md`.)

**Entries:**

- **Forth** (Chuck Moore, 1970). The canonical RPN stack-passing language; the colon-word/semicolon definition pattern; threaded code compilation; self-hosting via meta-compilation. `https://en.wikipedia.org/wiki/Forth_(programming_language)`. **Take:** the pure concatenative property — *"concatenation of two programs denotes the composition of the two functions they denote"* (Joy's formalization) — is the foundational claim. The DSL inherits the postfix syntax and the rejection of named lambda parameters (parameters are unnamed; they live on the stack).
- **ColorForth** (Chuck Moore, ~1990s). Color encodes semantics (define/compile/execute/variable). `https://en.wikipedia.org/wiki/ColorForth`. **Take:** the idea that visual/structural encoding can replace keywords, and the direct-mapped editor.
- **KYRA / VAMP** (Onat Türkçüoğlu, SVFIG 2025). 2-register stack (RAX/RDX); magenta pipe `|` as definition boundary emitting `RET + xchg rax, rdx`; basic blocks `[ ]` and lambdas `{ }` as compilation units; preemptive scatter. `C:\projects\forth\bootslop\references\kyra_in-depth.md`, `forth_day_2020_in-depth.md`. **Take:** the bracket operators (`[ ]`, `{ }`) and the arena-scoped blocks (`arena { }`).
- **x68 / 5th / "Ear" + "Toe"** (Timothy Lottes, 2007-2026). 32-bit instruction granularity; annotation overlay; folded interpreter; "register file as aliased global namespace" (X.com thread, lines 95-103). `C:\projects\forth\bootslop\references\neokineogfx_in-depth.md`, `blog_in-depth.md`. **Take:** the 32-bit token encoding, the annotation overlay pattern, the folded-interpreter optimization.
- **Joy** (William Byrd, Manfred von Thun, 2001-2003). Purely functional concatenative; quotations as first-class values; combinator library (`map`, `filter`, `fold`, `binrec`, `primrec`, `linrec`). `https://en.wikipedia.org/wiki/Joy_(programming_language)`. **Take:** the quotation-as-first-class-value concept and the combinator library as the model for Tier 2 verbs.
- **CoSy** (Bob Armstrong, ongoing). TimeStamped notebook/log in Forth; all nouns are lists/trees with 3-cell headers `(Type Count refCount)`; modulo indexing; "extensive vocabulary evolved from APL via K." `https://cosy.com/CoSy/Simplicity.html`, `https://cosy.com/4thCoSy/`. **Take:** the open-vocabulary culture; the modulo indexing (forgiving of off-by-one AI errors); the 3-cell header as a universal data structure.

**Section 5 grounding (per the cluster 1 synthesis).** The DSL's `->` pipeline, `[ ]`/`{ }` blocks, `arena { }` memory model, `scatter`/`gather` verbs, `map`/`filter`/`fold` combinators, modulo indexing, and the "no AST object" parsing strategy all have direct concatenative lineage. See `conductor/tracks/intent_dsl_survey_20260612/research/cluster_1_concatenative.md` §"Synthesis for Section 5" for the verb-by-verb mapping table.

### Cluster 2 — Array Languages (APL lineage)

**Cluster claim.** The DSL's *data model* — array as universal type, every verb vectorizes, multi-dimensional indexing — is the APL tradition as refined by K (ASCII-only with overloading), BQN (clean modern semantics with function trains), and Uiua (stack-based execution). The DSL inherits the *philosophy* (succinct expression of algorithms) but uses ASCII-compatible representation rather than APL's custom character set. (Per the full sub-report at `research/cluster_2_array.md`.)

**Entries:**

- **APL** (Kenneth Iverson, 1962; Turing Award 1979). The foundational array language; array as universal type; every glyph is a function; right-to-left evaluation with no precedence. `https://en.wikipedia.org/wiki/APL_(programming_language)`, `https://www.dyalog.com/`. **Take:** the array-as-universal-type principle and the right-to-left evaluation model.
- **K / q** (Arthur Whitney, KX Systems, 1993). ASCII-only with heavy context-sensitive overloading; first-class functions borrowed from Scheme; foundation of kdb+ in-memory columnar database. `https://en.wikipedia.org/wiki/K_(programming_language)`, `https://kx.com/`. **Take:** the context-sensitive operator philosophy and first-class functions.
- **BQN** (Marshall Lochbaum, 2020). Modernized APL with clean semantics; context-free grammar; function trains. `https://mlochbaum.github.io/BQN/`. **Take:** the train composition pattern as the most expressive tacit mechanism in the family.
- **Uiua** (Tony Morris, 2023). Stack-based execution; modern open-source development; online Pad for onboarding. `https://www.uiua.org/`, `https://github.com/uiua-lang/uiua`. **Take:** the stack-based execution model as a viable alternative to named parameters, and the modern onboarding-UX model.

**Section 5 grounding (per the cluster 2 synthesis).** The DSL's `for x .. n` (mapping to APL's `ιN` + reduce, BQN's `↕N`, K's `!R`) and `result[row, col]` (mapping to APL's multi-dim indexing, BQN's `⊏`, K's `@`) inherit directly from this cluster. See `conductor/tracks/intent_dsl_survey_20260612/research/cluster_2_array.md` §"Synthesis for the DSL" for the verb-by-verb mapping table.

### Cluster 3 — Intent-Mapping

**Cluster claim.** The DSL's *use case* — a compact, intent-expressive scripting language that maps user intent to platform-optimal operations — is the Jofito tradition as the user has been exploring it. The pipe-coalescing optimization (find/grep/sort/unique collapse into one in-memory script) is the runtime efficiency claim. The nagent tag protocol is *mentioned and explicitly rejected* (no XML angle brackets) but the *structured-protocol idea* is retained. (Per the full sub-report at `research/cluster_3_intent_mapping.md`.)

**Entries:**

- **Jofito** (Jody Bruchon, 2023-2026). "Intent mapping engine" (per 2026 README update); arena allocation; leader/chaser thread model; pipe-coalescing. `https://codeberg.org/jbruchon/jofito`, `docs/transcripts/Ddme7DwMQBI_jofito_jody_bruchon.txt`. **Take:** the "intent mapping engine" framing is the DSL's *use case*; the leader/chaser pattern is the *implementation hint*; the arena allocation is the *memory model*. (Specifically: the DSL's `scan -> filter -> print` chain is directly inspired by Jofito's `scandir(...) : filter : print` predicate chain.)
- **jq** (Stephen Dolan, 2012-). JSON-path filter language; the `|` pipe operator (replaced by `->` in the DSL). `https://en.wikipedia.org/wiki/Jq_(programming_language)`, `https://jqlang.org/`. **Take:** the filter-as-expression style; `select(condition)`, `map`, `reduce`, `unique` as Tier 2 verb precedents.
- **nagent's tag protocol** (per `conductor/tracks/nagent_review_20260608/agent_review_v2_1_20260612.md:50`, `decisions.md:50`). XML-ish self-closing tags (`<nagent-read path="..."/>`). **TAKEN:** the structured-protocol idea (named operation with typed attributes; LLM-emit-able; self-delimiting). **REJECTED:** the XML angle-bracket notation, per the user's explicit instruction: *"ignore its record formats as they problably will be less xml/json based as I don't like them"* (`decisions.md:50`). The DSL must use a different notation that preserves the structured-protocol properties.
- **WebAssembly** (W3C, 2017-). Linear memory; sectioned binary format; structured control flow. `https://en.wikipedia.org/wiki/WebAssembly`. **Take (one paragraph):** the linear memory model is the modern reference for the "tape drive" argument-passing semantics that grounds the DSL's Tier 2 verbs. The streaming-parse design suggests a parsing strategy where verb names and signatures are validated early (cheap) and arguments are parsed on demand (deferred).

**Section 4 grounding (per the cluster 3 synthesis).** Each Tier 2 verb cites Jofito (for `scan`, `filter`, `arena`, `scatter`, `gather`, `pipe`) or jq (for `select`, `map`, `fold`, `sort`, `dedupe`, `group`); each Tier 3 verb cites either nagent's structured-protocol idea (for `read`, `edit`, `test`, `discover`) or Jofito's tool-replacement model (for `glob`, `exec`, `run`, `mcp`). See `conductor/tracks/intent_dsl_survey_20260612/research/cluster_3_intent_mapping.md` §"Synthesis for the DSL" for the verb-by-verb mapping table.

### Cluster 4 — Meta-Tooling DSLs and Agent-Facing Languages

**Cluster claim.** The DSL is *not the first* agent-facing language. The existing `mcp_dsl_20260606` placeholder, nagent's "Bridge DSL" idea, OpenAI's function-calling schema, and Anthropic's tool-use schema are the prior art. The DSL learns from all four and takes a different notation (per the user's XML/JSON rejection) but the same structural properties (compact, structured, LLM-emit-able). (Per the full sub-report at `research/cluster_4_meta_tooling_dsls.md`.)

**Entries:**

- **`mcp_dsl_20260606`** (Manual Slop placeholder; per `conductor/tracks/mcp_architecture_refactor_20260606/spec.md` §12.1 and `nagent_review_20260608/metadata.json:28`). APL/K/Cosy-inspired per-MCP compact dialect. The closest project-internal reference. **Take:** the per-MCP grammar organization; the 8x token-reduction target (80 → 10 tokens); the JSON path stays (backward compat); the DSL is opt-in per MCP.
- **nagent's Bridge DSL idea** (per `nagent_takeaways_20260608.md` line 216-230). The bridge between external agents and actual `mcp_client.py` tool calls. **Take:** the Application's function-calling stays; the bridge DSL is the format external agents emit.
- **OpenAI function-calling** (per `https://platform.openai.com/docs/guides/function-calling`). JSON Schema with `strict`, `required`, `additionalProperties: false`, `enum` constraints. The 5-step conversational loop. **Take:** schema rigor baseline; token cost is proportional to schema verbosity; the 8x reduction target; namespace grouping; fewer-capable-tools principle.
- **Anthropic tool-use** (per `https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/define-tools`). Flat structure with `name`, `description`, `input_schema`, `input_examples`; `strict` as guarantee; `tool_choice` control. **Take:** `input_examples` as a model for teaching the DSL; `tool_choice` maps to Tier 4 verb design (auto/any/forced); the flat structure is the right model for terseness.

**Section 4 grounding (per the cluster 4 synthesis).** The Tier 4 verbs map to the entries as follows: `fuzzy` ← nagent Bridge + MCP DSL; `try`/`recover` ← nagent Bridge + OpenAI; `sandbox` ← OpenAI + Anthropic; `audit` ← MCP DSL + nagent Bridge; `didyoumean` ← nagent Bridge + Anthropic; `span` ← MCP DSL + OpenAI; `offset` ← MCP DSL + OpenAI; `assumewide` ← OpenAI + Anthropic. See `conductor/tracks/intent_dsl_survey_20260612/research/cluster_4_meta_tooling_dsls.md` §"Synthesis for the DSL" for the full mapping.

### Cluster 5 — SSDL Shape Primitives

**Cluster claim.** The DSL's verbs are annotated with **SSDL shape tags** (per `docs/reports/computational_shapes_ssdl_digest_20260608.md` §1) so the reader can see at a glance whether a verb is a single instruction, a codepath, a wide codepath, a codecycle, a wide codecycle, or a codecycle graph. This is the meta-vocabulary that lets the report describe a verb's *shape* in one token.

**The 6 SSDL primitives:**

| # | Shape | One-line definition | SSDL symbol |
|---|---|---|---|
| 1 | **Instruction** | A single unit of computation. Reads data, writes data, or both. | `[I]` |
| 2 | **Codepath** | A sequential list of instructions that *terminates*. No loops. | `->` |
| 3 | **Wide codepath** | A codepath whose execution *causes* several other codepaths to occur simultaneously. | `=>` |
| 4 | **Codecycle** | A circular structure — a codepath that *repeats* at its first instruction after its last. | `o->` |
| 5 | **Wide codecycle** | Multiple codecycles performing the same task simultaneously. | `o=>` |
| 6 | **Codecycle graph** | Multiple codecycles + the data they read and write. | `boxes + arrows` |

**The 7 modifiers:**

| Modifier | SSDL | Meaning |
|---|---|---|
| `[T]` | terminator | The instruction that *ends* a codepath (return, exit, etc.) |
| `[B]` | branch | A point where control flow forks based on a condition |
| `[M]` | merge | A point where control flow re-converges |
| `[S]` | stateful | Marks an instruction that *mutates* persistent state |
| `[Q]` | query | Marks an instruction that reads persistent state |
| `[N]` | nil sentinel | A special value that satisfies "is this OK to use?" in all cases |
| `───` | data | A line representing data being read or written (not a codepath) |

**How the DSL uses SSDL tags.** Each verb in §4 has a "Shape" column with an SSDL tag. For example, `sum` is `[I]` (single instruction); `for x .. n` is `o->` (codecycle); `arena { }` is a sub-codepath scope; `pipe` is `=>` (wide codepath, the chain can fan out); the entire DSL pipeline is a codecycle graph (multiple codecycles + the data they read and write). This lets the reader see the *shape* of a pipeline at a glance.

### Cluster 6 — Project's Own Command DSL Precedents

**Cluster claim.** The DSL is a *richer* superset of the project's existing 33 Command Palette commands (per `docs/guide_command_palette.md` and `src/commands.py`). The "Everything" mode in the Command Palette (per `guide_command_palette.md` line 383: *"search across commands, files, symbols, history, settings"*) is a near-term use case where the DSL's verbs can be the underlying format. The Command Palette is the user's existing vocabulary instinct; the DSL formalizes and extends it.

**5 representative commands by category** (the full 33 are in `docs/guide_command_palette.md`):

| Category | Command | Title | Action |
|---|---|---|---|
| AI | `reset_session` | Reset Session | `ai_client.reset_session()` + clears logs + `_handle_reset_session()` |
| AI | `clear_discussion` | Clear Discussion | Empties `app.discussion_history` |
| AI | `add_all_files_to_context` | Add All Files To Context | `app._add_all_files_to_context()` |
| View | `toggle_text_viewer` | Toggle Text Viewer | `_toggle_window(app, "Text Viewer")` |
| Tools | `trigger_hot_reload` | Hot Reload | `HotReloader.reload("src.gui_2", app)` |
| Layout | `save_workspace_profile` | Save Workspace Profile | Opens the save-profile modal |
| Theme | `cycle_theme` | Cycle Theme | Cycles through `["10x Dark", "ImGui Light", "NERV"]` |
| Help | `show_command_palette_help` | Show Command Palette Help | Loads `docs/Readme.md` into the Text Viewer |

**Take.** The DSL's verbs are a *richer* superset of these. Where the Command Palette has 33 imperative commands (each is a function with side effects), the DSL's Tier 2 verbs are declarative ("I want to scan, filter, print") and the Tier 4 verbs formalize the AI-fuzzing-tolerance aspects (audit, didyoumean) that the Command Palette cannot. The "Everything" mode in the Command Palette is the natural place where DSL verbs could appear as searchable entries.

### Cluster 7 — Data-Oriented Error Handling Convention

**Cluster claim.** The DSL's `try { ... } recover { ... }` envelope returns a `Result[T]` (with side-channel errors as `list[ErrorInfo]`), per the convention established by `conductor/tracks/data_oriented_error_handling_20260606/spec.md` §3.3. The 12 `ErrorKind` values are the canonical error vocabulary. The `Result[T]` dataclass is the data-oriented alternative to exception-based control flow.

**The 12 `ErrorKind` values** (per `data_oriented_error_handling_20260606/spec.md` §3.3):

| Kind | Meaning |
|---|---|
| `NETWORK` | Network or connection error |
| `AUTH` | Authentication / API key error |
| `QUOTA` | Quota exhausted |
| `RATE_LIMIT` | Rate limited |
| `BALANCE` | Balance / billing error |
| `PERMISSION` | Permission denied (file system, etc.) |
| `NOT_FOUND` | Resource not found |
| `INVALID_INPUT` | Invalid input (parse failure, schema mismatch) |
| `NOT_READY` | System not ready (e.g., RAG not initialized) |
| `UNKNOWN` | Unknown error |
| `CONFIG` | Configuration error |
| `INTERNAL` | Internal error (e.g., SDK exception) |
| `PROVIDER_HISTORY_DIVERGED_FROM_UI` | (added 2026-06-08; per nagent_review Pitfall #4) |

**The `Result[T]` dataclass signature** (per `data_oriented_error_handling_20260606/spec.md` §3.3):

```python
@dataclass(frozen=True)
class Result(Generic[T]):
    data: T
    errors: list[ErrorInfo] = field(default_factory=list)
    @property
    def ok(self) -> bool: return not self.errors
    def with_error(self, err: ErrorInfo) -> "Result[T]": ...
    def with_errors(self, new_errors: list[ErrorInfo]) -> "Result[T]": ...
    def with_data(self, new_data: T) -> "Result[T]": ...
```

**How the DSL uses the Result envelope.** The `try { ... } recover { ... }` block returns a `Result[T]` where `T` is the verb's return type. The `recover` block receives the `Result[T]` from the `try` and can inspect `.errors` to decide what to do. The `didyoumean` verb returns `Result[T, list[Suggestion]]` — the success case is the parse result, the failure case includes a list of suggested corrections.

---

## 3. The Grammar

The grammar formalizes 14 primitives drawn from the user's math pseudocode (the `determinate`/`minor`/`matrix-transpose` snippets shared during spec review), plus 3 known ambiguity flags, plus precedence rules and AI-fuzzing tolerance rules.

### 3.1 The 14 primitives

| # | Symbol | Name | Signature / Syntax | Meaning | Source example (user pseudocode) |
|---|---|---|---|---|---|
| 1 | `name := value` | Local bind | `name := expr` | Stack-scoped local declaration | `result := Matrix(m.rows -1, m.columns -1)` |
| 2 | `stack { ... }` | Stack scope | `stack { decl1; decl2; ... }` | Block of stack-allocated locals | `stack { result := ...; row_offset, col_offset := Scalar; }` |
| 3 | `name: Type` | Annotation | `name: Type` | Type hint on a binding | `m : Matrix` |
| 4 | `func(args) -> Type { ... }` | Function def | `func(args) -> Type { body }` | Named function with return type | `determinate(m, row) -> Scalar { ... }` |
| 5 | `name(...) proc { ... }` | Procedure def | `name(args) proc { body }` | Void-returning function | `minor(m, row_omit, column_omit) -> Scalar proc { ... }` |
| 6 | `for x .. n` | Range iteration | `for x .. n { body }` | Iterate `x` over `[0, n)` | `for col .. m.columns` |
| 7 | `name[a, b]` | Bracket indexing | `name[i, j, k, ...]` | Multi-dim array access | `result[row - row_offset, col - col_offset]` |
| 8 | `if cond { ... }` | Conditional | `if cond { then-body }` | If-then (else inferred) | `if col = col_omit { ++ col_offset; continue; }` |
| 9 | `return value` | Return | `return expr` | Function exit with value | `return result` |
| 10 | `->` (between verbs) | Pipeline flow | `verb1 -> verb2 -> verb3` | Output of left → input of right | `filter -> (col != column_omit <- for col .. m.columns)` |
| 11 | `<-` (after verb) | Input binding | `result <- producer` | The thing on the right is the producer | `for col .. m.columns` produces; `col != column_omit` consumes |
| 12 | `=` (in `assert`) | Equality | `assert -> lhs = rhs` | Assert two expressions are equal | `assert -> product(...) = product(...)` |
| 13 | `{ }` | Body block | `{ body }` | Function/scope body | `{ ... }` |
| 14 | `[ ]` | Basic block | `[ my_stage ]` | Onat's compilation unit (no branching semantics) | (not in user pseudocode; from KYRA's basic blocks) |

### 3.2 Ambiguity flags

Per the user's note during spec review (*"Hopefully the above don't have too many logic errors that the use can't be clarified."*), three known ambiguities in the user's pseudo code are normalized in the report:

- **`proc` modifier placement:** `minor(m, row_omit, column_omit) -> Scalar proc { ... }` — likely a *type qualifier* (the return type is "Scalar" + "proc"-ness means side-effecting). The report adopts the convention that `proc` is a postfix modifier indicating void-returning; the syntax is `name(args) proc { body }` (return type omitted) or `name(args) -> Type proc { body }` (return type explicit but ignored).
- **`++col_offset`:** likely `col_offset += 1`. The report formalizes as `name += 1` (Python-style augmented assignment) and does not adopt the `++` operator. This avoids confusion between pre-increment and post-increment.
- **`m[row][column]` vs `m[row, col]`:** both appear in the user's snippets (line 24 `m[row][column]` is likely a typo for `m[row][col]`). The report adopts the comma-form (`name[a, b]`, multi-dim) throughout, since the C-style chained-bracket form doesn't compose with the user's existing matrix pseudocode.

### 3.3 Precedence rules

- **Left-to-right for `->` chains:** `a -> b -> c` parses as `(a -> b) -> c` (b's output becomes c's input). This is *not* the standard math convention (right-to-left) but it matches the user's pseudocode and the pipeline model.
- **`(` `)` for grouping:** explicit parentheses override the left-to-right default. `a -> (b -> c)` parses as `a -> X` where `X = (b -> c)`.
- **Stack-binding precedence:** `:=` binds tighter than `<-`. `result := expr <- producer` parses as `result := (expr <- producer)`.
- **No operator precedence for arithmetic:** `+`, `-`, `*`, `/`, `^` are all left-associative with equal precedence. `2 + 3 * 4` parses as `(2 + 3) * 4 = 20`. (This is the APL/K convention. If the user wants math precedence, the report can adopt explicit `(` `)`.)

### 3.4 AI-fuzzing tolerance rules

These are the rules that make the DSL workable for AI agents that may fuzz verb names, indent inconsistently, or offset line references.

- **CoSy-style modulo indexing:** array indices wrap. `result[-1]` is equivalent to `result[result.len - 1]`. This forgives AI off-by-one errors in line references. (Per the CoSy Simplicity page: *"Indexing is modulo - like counting on your thumb & fingers : 0 1 2 3 4 0."*)
- **Structured recovery anchors via `{ }`:** the `{ }` block is a recovery unit. If the parser cannot parse the body, the entire block is replaced with `NIL` and the error is reported at the block level, not at the line level.
- **Line/offset independence:** the parser uses *token positions*, not raw line numbers. A token's position is `file:token-index` (e.g., `src/foo.py:42` means "the 42nd token in src/foo.py"), not `file:42` (which would be "line 42"). The mapping from token position to line number is a presentation concern, not a parse concern. This matches the project's existing FuzzyAnchor pattern (per `docs/guide_context_curation.md`).
- **Verb-name fuzzing tolerance:** the `didyoumean` verb (see §4 Tier 4) proposes corrections for ambiguous verb names. The parser's "best guess" recovery path is configurable: strict (reject on typo), lenient (auto-correct if Levenshtein distance ≤ 2), or fuzzy (parse the rest, log the typo).
- **Indentation tolerance:** indentation is *not* significant (per the user's explicit "ignore its record formats" instruction and the rejection of Python's indent-sensitive syntax). The parser uses a stack-based approach; the `{ }` and `[ ]` delimiters are the only structure-aware tokens.

### 3.5 Error envelope: `try { ... } recover { ... }`

```
try {
    scan "src/foo.py" -> filter !exists -> print
} recover err {
    audit "scan failed: " + err
    return NIL
}
```

- The `try` block evaluates the pipeline. If the pipeline returns a `Result[T]` with `errors` non-empty, the `recover` block runs.
- The `recover` block receives the `Result[T]` as a parameter (named by the user; `err` is the default convention from the user's pseudocode).
- The `recover` block must return a `Result[T]` (or `NIL` to short-circuit).
- If the `recover` block itself returns a `Result[T]` with errors, those errors are appended to the outer `Result[T]`'s error list. (Per Fleury's "errors are data" pattern; per `data_oriented_error_handling_20260606/spec.md` §3.4.)

### 3.6 Block composition: `[ ]` (KYRA basic blocks) vs `{ }` (body blocks) vs `arena { }` (tape regions)

- **`[ ]`** is Onat's basic block (per `C:\projects\forth\bootslop\references\kyra_in-depth.md:56-57`): *"Basic blocks `[ ]` provide implicit begin/link/end jump targets for the JIT to resolve relative offsets within a limited scope."* In the DSL, `[ ]` is a *sequential operation block* — a chunk of code that the parser can compile and dispatch as a unit. It is *not* a scope (no new bindings); it is a *compilation unit*.
- **`{ }`** is a body block: function body, if/then body, recover body. It introduces a new lexical scope (new bindings are local to the block).
- **`arena { }`** is a tape-drive region: a `{ }` body that has been *pre-scattered* into a contiguous memory region. The contents are pre-placed; the JIT can emit the entire block as a single `xchg rax, rdx` boundary (per KYRA's magenta pipe semantics).

The three are nested by the parser: `arena { foo := x; [ bar ]; baz }` is a tape region containing 2 sequential statements (the local bind and the basic block) and a trailing call.

---

## 4. The 4-Tier Vocab (~40 Verbs)

Each verb: symbol, name, signature, one-line semantics, one example, "borrowed from" note, SSDL shape tag. Tier 2 and Tier 3 verbs also have a "maps to mcp_client tool" column. Tier 4 verbs have a "novel piece" note.

### 4.1 Tier 1 — Math (~10 verbs)

The Tier 1 verbs are drawn directly from the user's math pseudocode.

| Symbol | Name | Signature | Semantics | Example | Borrowed from | Shape |
|---|---|---|---|---|---|---|
| `:=` | Local bind | `name := expr` | Stack-scoped local declaration | `result := Matrix(m.rows -1, m.columns -1)` | Forth (dictionary entries); Joy (quotations) | `[I]` |
| `stack { ... }` | Stack scope | `stack { decl1; decl2; ... }` | Block of stack-allocated locals | `stack { result := ...; row_offset, col_offset := Scalar; }` | Forth (colon definitions); KYRA (basic blocks) | `[I]` |
| `for x .. n` | Range iteration | `for x .. n { body }` | Iterate `x` over `[0, n)` | `for col .. m.columns` | APL `ιN`; K `!R`; BQN `↕N`; Uiua (stack iteration) | `o->` |
| `+` | Add | `a + b` | Element-wise sum | `2 + 3` (yields 5) | All languages | `[I]` |
| `-` | Subtract | `a - b` | Element-wise difference | `5 - 2` (yields 3) | All languages | `[I]` |
| `*` | Multiply | `a * b` | Element-wise product | `2 * 3` (yields 6) | All languages | `[I]` |
| `/` | Divide | `a / b` | Element-wise division | `6 / 2` (yields 3) | All languages | `[I]` |
| `^` | Power | `a ^ b` | Element-wise power | `2 ^ 10` (yields 1024) | All languages | `[I]` |
| `sum` | Sum | `sum expr` | Sum all elements | `sum 1..10` (yields 55) | APL `+/`; K `+/`; BQN `+` | `[I]` |
| `product` | Product | `product expr` | Product all elements | `product 1..5` (yields 120) | APL `×/`; K `*/`; BQN `×` | `[I]` |
| `a[i, j]` | Bracket indexing | `name[i, j, ...]` | Multi-dim array access | `result[row - row_offset, col - col_offset]` | APL `result[2;3]`; BQN `⊏`; K `@` | `[Q]` (query) |
| `if/then` | Conditional | `if cond { then-body }` | If-then (else inferred) | `if col = col_omit { ++ col_offset; continue; }` | Forth (IF/THEN); CoSy (control flow) | `[B]` (branch) |

**Total Tier 1: 12 verbs.** (Slightly over the 10 estimate; the verbs are tight enough that splitting them hurts readability.)

### 4.2 Tier 2 — Data-Oriented Pipeline (~12 verbs)

The Tier 2 verbs wrap the existing 45+ MCP tools (per `docs/guide_tools.md` §"Native Tool Inventory") with declarative intent expressions. They are the "imperative veneer" over the Jofito-style predicate chain.

| Symbol | Name | Signature | Semantics | Example | Maps to mcp_client tool | Borrowed from | Shape |
|---|---|---|---|---|---|---|---|
| `scan` | Scan | `scan path` | Read source (directory, file, URL); first verb in every pipeline | `scan "src/" -> filter !dir -> map ext` | `list_directory` + `search_files` + `read_file` | Jofito `scandir()` | `[I]` |
| `select` | Select | `select condition` | Keep records matching condition (jq-style filter) | `scan "src/" -> select .extension == ".py"` | (jq-style filter) | jq `select(condition)`; Joy `filter` | `->` |
| `filter` | Filter | `filter predicate` | Keep records where predicate is true | `scan "src/" -> filter .size > 0` | (predicate on FileItem) | Jofito `{filter ...}` predicate | `->` |
| `map` | Map | `map block` | Apply block to each record | `scan "src/" -> map ext` | (no direct equivalent) | jq `.[] | .field`; Joy `map`; CoSy `' verb 'm` | `o->` |
| `fold` | Fold | `fold init block` | Reduce to single value | `scan "src/" -> fold 0 { acc + .size }` | (no direct equivalent) | jq `reduce`; Joy `fold` | `o->` |
| `sort` | Sort | `sort key` | Order records by key | `scan "src/" -> sort .name` | (no direct equivalent) | Joy `qsort`; jq `sort` | `[I]` |
| `group` | Group | `group key` | Bucket records by key | `scan "src/" -> group .extension` | (no direct equivalent) | jq `group_by`; CoSy APL-derived | `o->` |
| `dedupe` | Dedupe | `dedupe` | Remove duplicates | `scan "src/" -> dedupe` | (no direct equivalent) | jq `unique`; CoSy | `[I]` |
| `arena { }` | Arena scope | `arena { body }` | Tape-drive region; pre-scatter contents | `arena { [ scan ]; [ filter ]; [ print ] }` | (compiler directive) | KYRA magenta pipe; Onat preemptive scatter | `o->` |
| `scatter` | Scatter | `scatter workers` | Fork pipeline across `workers` cores | `scan "src/" -> scatter 4 -> filter` | (runtime hint) | Onat preemptive scatter; Lottes X.com thread line 55-61 | `=>` |
| `gather` | Gather | `gather` | Collect scattered sub-streams | `scan "src/" -> scatter 4 -> filter -> gather` | (runtime hint) | Onat inverse of scatter | `[I]` |
| `pipe` | Pipe root | `pipe` | Explicit chain root (synonym for `->`) | `pipe [ scan, filter, print ]` | (no direct equivalent) | Jofito pipe coalescing (transcript:376-410) | `=>` |

**Total Tier 2: 12 verbs.**

### 4.3 Tier 3 — Shell (~10 verbs)

The Tier 3 verbs wrap existing MCP tools (per `docs/guide_tools.md` §"Native Tool Inventory") and provide the shell-scripting surface. They are the "imperative veneer" over the declarative Tier 2 pipeline.

| Symbol | Name | Signature | Semantics | Example | Maps to mcp_client tool | Borrowed from | Shape |
|---|---|---|---|---|---|---|---|
| `exec` | Execute | `exec cmd` | Run shell command | `exec "find . -name '*.py'"` | `run_powershell` (shell_runner.py) | nagent tag protocol (structured protocol idea) | `[I]` |
| `open` | Open | `open path` | Open file/URL | `open "src/foo.py"` | `read_file` | nagent tag protocol | `[I]` |
| `read` | Read | `read path` | Read file content | `read "src/foo.py"` | `read_file` | nagent tag protocol | `[I]` |
| `write` | Write | `write path content` | Write file content | `write "src/foo.py" "new content"` | `set_file_slice` / `edit_file` | nagent tag protocol | `[I]` |
| `close` | Close | `close handle` | Close handle | `close file_handle` | (no direct equivalent; close is implicit in Python) | Forth `CLOSE-FILE`; bash `exec` | `[I]` |
| `path` | Path | `path` | Get current path (or `cd`) | `path` | (no direct equivalent; use `cwd`) | shell `pwd`; CoSy `path` | `[I]` |
| `env` | Env | `env var` | Get env var | `env HOME` | (no direct equivalent) | shell `echo $HOME` | `[I]` |
| `wait` | Wait | `wait ms` | Block for `ms` milliseconds | `wait 1000` | (no direct equivalent) | shell `sleep` | `o->` |
| `poll` | Poll | `poll handle ms` | Poll handle with timeout | `poll file_handle 5000` | (no direct equivalent) | shell `read -t` | `o->` |
| `cwd` | CWD | `cwd` | Get current working directory | `cwd` | (no direct equivalent) | shell `pwd` | `[I]` |

**Total Tier 3: 10 verbs.**

### 4.4 Tier 4 — AI-Fuzzing Tolerance (~8 verbs, the novel contribution)

The Tier 4 verbs are what make the DSL workable for AI agents that may fuzz verb names, indent inconsistently, or offset line references. Each verb directly maps to one or more of the 4 anchor claims (especially Claim 3: IEventTarget, per Cluster 0).

| Symbol | Name | Signature | Semantics | Example | Novel piece | Borrowed from | Shape |
|---|---|---|---|---|---|---|---|
| `fuzzy` | Fuzzy | `fuzzy expr` | Declare a parse-tolerance region; parser accepts near-matches | `fuzzy { scan "src/" -> filter .ext }` | Tolerance for AI verb-name fuzzing | nagent "discovery" intent (per `decisions.md:119,128`); SSDL "assume as much as possible" | `->` |
| `try { ... } recover { ... }` | Try / Recover | `try { body } recover err { fallback }` | Returns `Result[T]`; on error, the `recover` block runs | `try { read "src/foo.py" } recover { read "src/Foo.py" }` | Error envelope as data (Fleury pattern) | `data_oriented_error_handling_20260606`; Wasm `try`/`catch` block/loop/if/end | `->B->` |
| `sandbox { ... }` | Sandbox | `sandbox { body }` | IEventTarget boundary; all writes in the block go through the formal event channel | `sandbox { write "tmp/x" "data" }` | O'Donnell's "reads free, writes formalized" invariant applied to the DSL | O'Donnell `mvc.html` "Writing to Model state" | `o->` |
| `audit` | Audit | `audit msg` | Log the state change to a structured record; the IEventTarget itself | `audit "wrote tmp/x"` | Per-write audit log; full replay capability | O'Donnell `mvc.html` "Event callbacks"; nagent's self-describing tools | `[I]` |
| `didyoumean` | Did you mean | `didyoumean ambiguous` | Propose the closest matching verb(s) for an ambiguous input | `didyoumean "skan"` | Recovery primitive for AI typos | nagent Bridge DSL intent model; Anthropic `input_examples` | `[I]` |
| `span` | Span | `span intent` | Decompose a compound intent into a span of sub-MCP grammar tokens | `span "read foo.py:MyClass"` | Spans the `read_file` and `py_get_definition` tools | MCP DSL per-MCP grammar (`spec.md:456-465`); OpenAI namespace grouping | `[I]` |
| `offset` | Offset | `offset symbol` | Resolve a symbol to a file:line without requiring the model to specify the line | `offset "foo.py:MyClass.method"` | Implicit offset resolution | MCP DSL line-range notation; OpenAI "don't make the model fill known args" | `[Q]` |
| `assumewide` | Assume wide | `assumewide intent` | If the intent is broad or ambiguous, select the most-capable matching tool (the "fewer, more capable" heuristic) | `assumewide "refactor"` | Prefer broad-capability tools over narrow specialists | OpenAI "fewer than 20 functions"; Anthropic `tool_choice: tool` force-call | `=>` |

**Total Tier 4: 8 verbs.**

**Total vocab: 12 + 12 + 10 + 8 = 42 verbs.** (~40 estimate; slightly over because Tier 1 is 12 instead of 10, but Tier 3 is 10 and Tier 4 is 8.)

---

## 5. Hardware Mapping (4 Anchor Claims)

The 4 anchor claims tie the vocab and grammar to actual hardware/software stages.

### 5.1 Claim 1 — Onat/Lottes, hardware

The DSL's `->` pipeline, `[ ]`/`{ }` blocks, `arena { }` memory model, and `scatter`/`gather` verbs are direct descendants of KYRA/VAMP and x68.

- **`->` pipeline:** inherits from Forth's postfix word chain, refined by KYRA's 2-register stack (RAX/RDX) as the minimal call convention. Per `C:\projects\forth\bootslop\references\kyra_in-depth.md:14` (*"The 2-Item Hardware Stack: To achieve hardware locality and GPU compatibility, KYRA strictly restricts the data stack to exactly two CPU registers: `RAX` (Top of Stack) and `RDX` (Next on Stack)"*).
- **`[ ]` sequential block:** inherits from KYRA's basic blocks `[ ]` with implicit begin/link/end jump targets. Per `kyra_in-depth.md:56-57` (*"Basic Blocks `[ ]`: These visually constrain the assembly output. They provide implicit begin, link (else), and end jump targets for the JIT to resolve relative offsets within a limited scope"*).
- **`{ }` lambda block:** inherits from KYRA's lambdas `{ }` that compile code elsewhere and leave an address in `RAX`. Per `kyra_in-depth.md:58-59` (*"Lambdas `{ }`: A lambda (colored Yellow `{`) does not execute inline. The JIT compiles the block of code elsewhere in the arena and leaves its executable memory address in `RAX`."*).
- **`arena { }`:** inherits from KYRA's magenta pipe `|` definition boundary (`RET` + `xchg rax, rdx`) as the entry/exit protocol for a memory region. Per `kyra_in-depth.md:24-27` (*"The Magenta Pipe Trick: Because the stack is just `RAX` and `RDX`, ensuring `RAX` is the active 'Top of Stack' before executing a word is vital. The `xchg rax, rdx` instruction compiles to a tiny 2-byte opcode: `48 92`. Definitions: There are no `begin` or `end` words. A magenta pipe token (`|`) implicitly signals the start of a new definition. The JIT reacts to this by: 1. Emitting a `RET` (`C3`) to close the *previous* definition. 2. Emitting `48 92` (`xchg rax, rdx`) to ensure proper stack alignment for the *new* definition."*).
- **`scatter`:** inherits from Onat's preemptive scatter — per `X.com - Onat & Lottes Interaction 1.png.ocr.md:59-61`: *"The key concept here is that 'common' arguments like the device are pushed onto the tape using store duplication when they are known (after device creation). So it's preemptive scatter, so later at call time there is no argument gather."*
- **`gather`:** the inverse of preemptive scatter — collect pre-scattered values from fixed memory slots.

Lottes's specific framing at `X.com - Onat & Lottes Interaction 1.png.ocr.md:80-86`: *"I laugh when people say C is like assembly, they are missing what we did in assembly back then, which was all registers and globals and gotos, no stacks. It's radically different than good assembly."* The DSL's 2-register model + arena regions + magenta `->` are a direct application of this insight: don't pretend you have a memory stack when the hardware has registers.

### 5.2 Claim 2 — O'Donnell, paradigm

The DSL's pipeline is *immediate-mode in pipeline composition*. Each `->`-delimited stage is a method invocation, not a Pipeline object. The pipeline exists *only* while the DSL program is being executed; once execution ends, the pipeline's state is gone.

Per O'Donnell at `https://johno.se/book/imgui.html`: *"Widgets, logically, change from being objects to being method invocations. As we shall see, this fundamentally changes how a client application approaches the implementation of user interfaces."*

The DSL inherits this: `scan -> filter -> print` is not a pipeline object you can query, name, or pass around. The only way to "name" a chain is to wrap it in a function (`determinate(m, row) -> Scalar { ... }`). The function body IS the chain; the function name IS the chain's identity. There is no separate Pipeline class.

This also means: the parser doesn't need to track pipeline state across executions. Each invocation of `determinate(m, row)` is independent. There is no "current pipeline" implicit state. The next call is fresh.

### 5.3 Claim 3 — Forth/CoSy, syntax

Concatenative syntax is immediate-mode in *tokenization* (whitespace-delimited, no precedence), in *evaluation* (each verb pops args, pushes results), and in *parsing* (no AST object retained after the parse — the parser emits JIT'd code directly per Onat's xchg model).

- **Tokenization:** whitespace-delimited, no precedence table. Per `https://en.wikipedia.org/wiki/Forth_(programming_language)`: *"Forth's grammar has no official specification. Instead, it is defined by a simple algorithm. The interpreter reads a line of input from the user input device, which is then parsed for a word using spaces as a delimiter."*
- **Evaluation:** each verb pops args, pushes results. Per CoSy Simplicity: *"Words pass information to each other by pushing it on, or taking it off a `stack`."*
- **Parsing:** no AST object retained after parse. The parser emits directly. Per `data_oriented_error_handling_20260606/spec.md` §3.1 and the project's overall "data-oriented design" philosophy, parsing is data flow, not object construction.

The DSL inherits all three. The parser reads whitespace-delimited tokens, evaluates each verb as a stack effect, and emits the result without retaining an AST.

### 5.4 Claim 4 — APL/K, data

Array languages are immediate-mode in *data representation*. There is no array-object header; values are passed by stack reference, not by handle.

- **APL** (per `https://en.wikipedia.org/wiki/APL_(programming_language)`): *"APL has an array as the universal data type"* — scalar `5` is a 0-dimensional array; `4 5 6 7 + 4` propagates the addition across the vector.
- **K** (per `https://en.wikipedia.org/wiki/K_(programming_language)`): "kdb+ (built on K) processes billions of records at microsecond latency" — the array paradigm scales to production workloads.
- **BQN** (per `https://mlochbaum.github.io/BQN/`): the CBQN bytecode compiler confirms the paradigm can be compiled efficiently.

The DSL's `for x .. n` range + `result[row, col]` indexing inherits the "no array object" property. The array is *the* universal type; every function operates on it; every function vectorizes.

---

## 6. AI-Agent Properties (10 Claims)

The 10 claims tie the DSL to the existing project's architecture so future tracks can build on it without re-deriving the design.

### 6.1 Claim 1 — Domain = Meta-Tooling

The DSL is **Meta-Tooling-side** per `docs/guide_meta_boundary.md` §"Domain 2: The Meta-Tooling". The Application's provider-native function-calling stays unchanged. The DSL is the format external agents (Gemini CLI, OpenCode) emit when invoking `mcp_client.py` tools.

### 6.2 Claim 2 — Runtime path = external agent → DSL → bridge → MCP → optional Hook API approval

Per `docs/guide_meta_boundary.md` §"The Inter-Domain Bridges": external agents (Gemini CLI) call the DSL via a bridge script (`scripts/cli_tool_bridge.py` analogue). The bridge script translates the DSL into `mcp_client.dispatch()` calls. The Hook API (`docs/guide_tools.md` §"The Hook API") surfaces HITL approval modals when the bridge detects a `sandbox { ... }` block.

### 6.3 Claim 3 — 3-layer security

The DSL's parser respects the existing 3-layer security model in `mcp_client.py` (per `docs/guide_tools.md` §"The MCP Bridge"). Every DSL statement that targets a tool outside the allowlist is rejected at parse time. The 3 layers are: allowlist construction, path validation, and resolution gate. The DSL does not bypass any of these.

### 6.4 Claim 4 — 4 memory dimensions

The DSL does *not* replace any of the 4 memory dimensions (per `conductor/tracks/nagent_review_20260608/nagent_review_v2_1_20260612.md` §2.1):
- **Curation memory** (FileItem + ContextPreset + FuzzyAnchor)
- **Discussion memory** (disc_entries + branching + UISnapshot A1-A7)
- **RAG memory** (ChromaDB, opt-in)
- **Knowledge memory** (Candidate 11, the harvested durable learnings)

The DSL is a *query format* for all 4, not a replacement. A `scan "src/foo.py"` is a curation-memory query; a `select .role == "User"` is a discussion-memory query; a `search "execution clutch"` is a RAG-memory query; a `read "knowledge/digest.md"` is a knowledge-memory query.

### 6.5 Claim 5 — Stable-to-volatile cache ordering

The DSL's `arena { }` blocks are cache-friendly per nagent v2.1 §2.2 stable-to-volatile ordering. The DSL's audit logs (Tier 4 `audit` verb) are a *stable* layer that can be cached across turns. The DSL's pipeline output (e.g., the output of `scan -> filter`) is a *volatile* layer appended per turn.

### 6.6 Claim 6 — `Result[T]` envelope

The DSL's `try { ... } recover { ... }` verb returns `Result[T]` per the convention established by `conductor/tracks/data_oriented_error_handling_20260606/spec.md` §3.3. The 12 `ErrorKind` values are the canonical error vocabulary. The `Result[T]` dataclass is the data-oriented alternative to exception-based control flow.

### 6.7 Claim 7 — Command Palette 33 commands

The DSL's verbs are a *richer* superset of the 33 Command Palette commands (per `docs/guide_command_palette.md` and `src/commands.py`). The "Everything" mode in the Command Palette (per `guide_command_palette.md` line 383: *"search across commands, files, symbols, history, settings"*) is a near-term use case where the DSL's verbs can be the underlying format. The user types `find "execution clutch"` instead of clicking on a result; the DSL parses the intent and dispatches to the right MCP tool.

### 6.8 Claim 8 — Hook API state fields

The DSL's verbs that mutate state route through `_predefined_callbacks` (per `docs/guide_state_lifecycle.md` §"Hook API Surface"). The verbs that read state use `_gettable_fields`. The DSL never bypasses the Hook API; it's a *user* of the existing infrastructure.

### 6.9 Claim 9 — O'Donnell's IEventTarget pattern as the `sandbox` verb

The `sandbox { ... }` block in Tier 4 is the DSL's IEventTarget boundary. Per O'Donnell at `https://johno.se/book/mvc.html` "Writing to Model state": *"Writes to Model are formalized through the addition of IEventTarget. This is a pure virtual interface that defines all possible state changes / events on a system wide level."* In the DSL, `sandbox { ... }` declares: every state change in this block goes through a single auditable interface (the bridge script's HITL approval modal per `docs/guide_meta_boundary.md`). The `audit` verb is the IEventTarget itself: a write-verb that logs the state change to a structured record (timestamp, source, kind, payload — same shape as `guide_architecture.md` §"Telemetry & Auditing" `Comms Log` entries).

Per the cluster 0 sub-report (per `cluster_0_odonnell.md` §"Connections" Connection 1): *"The `sandbox` verb isolates execution and enforces that all state observations by the sandboxed code are *reads* — they can occur freely against the const Model view. State mutations by sandboxed code, however, must be routed through the formal event channel."*

### 6.10 Claim 10 — O'Donnell's "reads are free" claim as the rationale for cheap verbs

Per O'Donnell at `https://johno.se/book/mvc.html` "Reading Model state": *"First of all, View and Controller may only access Model in a const fashion. This has numerous repercussions. Firstly, exposing central Model state as public is ok, as it can only be read. Also, only const methods may be called, so state changes cannot be made internally as a result of a bad function call."*

The Tier 2 verbs (`scan`, `filter`, `map`, `fold`, `sort`, `group`, `dedupe`) are *read-only* and can be re-evaluated freely, multiple times per execution, in parallel stages, without audit. Only the moment the chain's output is consumed by a write-verb (`exec`, `write`, `assign`) triggers the HITL modal. This is why the bridge script can re-execute a read-only chain without human approval.

Per the cluster 0 sub-report (per `cluster_0_odonnell.md` §"Connections" Connection 2): *"O'Donnell's 'reads are free' claim is the rationale for cheap Tier 2 verbs — they can be re-evaluated freely because they never mutate state, so they can be re-evaluated freely, multiple times per execution, in parallel stages, without audit."*

---

## 7. Open Questions for Follow-up B (≥6)

These open questions must be answered by the follow-up B track (interpreter prototype). Each question is a design decision the interpreter must make.

1. **How does `arena { }` map to Onat's preemptive scatter?** Is the block itself a tape-drive region, or is `arena` a wrapper that allocates a tape for the block's contents? The interpreter must decide whether `arena { ... }` is a parser hint (the parser pre-scatters) or a runtime directive (the runtime allocates a tape). The implication: parser-time optimization vs runtime flexibility.

2. **Where does "intent resolution" live?** Is it a per-verb option, a per-block modifier, or a global parser mode? The `fuzzy` verb declares a parse-tolerance region; is this a property of the verb, of the block, or of the whole program? The interpreter must decide how `fuzzy` composes with non-`fuzzy` verbs in the same chain.

3. **How does `audit` interact with `comms.log`?** Per `docs/guide_architecture.md` §"Telemetry & Auditing", the existing 5 log streams are `comms.log` (JSON-L for API traffic), `toolcalls.log` (markdown for tool invocations), `apihooks.log` (HTTP hook invocations), `clicalls.log` (subprocess details), and `scripts/generated/<ts>_<seq>.ps1` (preserved scripts). Is the DSL's audit log a 6th stream, or does it fold into one of the existing 5? Recommendation: a 6th stream (`audit.log`) because the DSL's audit is verb-level (every verb), while the existing 5 streams are tool-level (specific call types).

4. **Does `sandbox` produce `Result[T, ErrorInfo]` (the Fleury pattern) or a different envelope?** Per `data_oriented_error_handling_20260606/spec.md` §3.3, the canonical `Result[T]` is a dataclass with `data: T` and `errors: list[ErrorInfo]`. The `sandbox { ... }` block can either use this envelope or a different one (e.g., `SandboxResult` with `stdout: str`, `stderr: str`, `exit_code: int`, `errors: list[ErrorInfo]`). The interpreter must decide.

5. **`didyoumean` recovery: parser feature or user-facing verb?** If parser feature, the parser auto-corrects on parse failure and the user never sees the typo. If user-facing verb, the parser logs the typo, the user writes `didyoumean "<typo>"`, and gets a suggestion. The interpreter must decide whether `didyoumean` is part of the parse path or part of the runtime path.

6. **How does `for x .. n` interact with Tier 2's `filter`/`map`?** Is `for x .. n { body }` sugar for `[1, 2, ..., n] -> map { body }`? Or are they distinct (the for-loop has named variable, the pipeline has anonymous position)? The interpreter must decide whether the user's pseudocode `for col .. m.columns { body }` is syntactic sugar for the array-language `iota m.columns { ... }`.

7. **How does `sandbox` map to Manual Slop's `pre_tool_callback` flow?** The `sandbox` block's audit log: separate JSON-L file, or fold into the existing `comms.log` + `toolcalls.log`? (This is the same question as #3, but specifically about the runtime path — what happens when a `sandbox { write "tmp/x" "data" }` is actually executed by the bridge script?)

8. **Connection to `intent_dsl_for_meta_tooling_20260608_PLACEHOLDER`:** what's the minimum subset of the report's vocab that would let the placeholder track (a) write a bridge script and (b) demonstrate one round-trip end-to-end? The placeholder's per-MCP grammar design (per `mcp_architecture_refactor_20260606/spec.md` §12.1) needs at least 1 Tier 1 verb, 1 Tier 2 verb per sub-MCP, and 1 Tier 4 verb (probably `sandbox` or `audit`). The minimum subset: 1-3 verbs, plus the grammar.

---

## Appendix: Bibliography

### A.1 External prior art

**Cluster 0 — Immediate-Mode Paradigm:**
- John O'Donnell, "IMGUI" — `https://johno.se/book/imgui.html` (widgets as method invocations, frame shearing, deferred display)
- John O'Donnell, "The Pitch" — `https://johno.se/book/pitch.html` (paradigm shift, GPU advances, Controller as procedural composer)
- John O'Donnell, "Immediate Mode MVC" — `https://johno.se/book/immvc.html` (book roadmap, IEventTarget centrality)
- John O'Donnell, "MVC" — `https://johno.se/book/mvc.html` (reads free/writes formalized, IEventTarget pattern, scene-graph prohibition)

**Cluster 1 — Concatenative (Forth family):**
- Forth — `https://en.wikipedia.org/wiki/Forth_(programming_language)` (RPN, dictionary, colon-word, threaded code, self-hosting)
- ColorForth — `https://en.wikipedia.org/wiki/ColorForth` (color-encoded semantics)
- KYRA/VAMP (Onat Türkçüoğlu) — `C:\projects\forth\bootslop\references\kyra_in-depth.md` (2-register stack, magenta pipe, basic blocks, lambdas, FFI), `forth_day_2020_in-depth.md` (ColorForth + SPIR-V)
- x68/5th (Timothy Lottes) — `C:\projects\forth\bootslop\references\neokineogfx_in-depth.md` (folded interpreter, 32-bit granularity, annotation overlay), `blog_in-depth.md` (source-less evolution, "Ear"+"Toe"), `Architectural_Consolidation.md` (synthesis)
- Onat/Lottes X.com thread — `C:\projects\forth\bootslop\references\X.com - Onat & Lottes Interaction 1.png.ocr.md` (direct quotes on register file as aliased namespace, preemptive scatter, "no stacks")
- Joy — `https://en.wikipedia.org/wiki/Joy_(programming_language)`, `http://joylang.org/` (purely functional concatenative, quotations as first-class values, combinator library)
- CoSy (Bob Armstrong) — `https://cosy.com/CoSy/Simplicity.html` (TimeStamped notebook/log, 3-cell headers, modulo indexing, APL-via-K vocabulary), `https://cosy.com/4thCoSy/` (4thCoSy repo)

**Cluster 2 — Array:**
- APL (Kenneth Iverson) — `https://en.wikipedia.org/wiki/APL_(programming_language)`, `https://www.dyalog.com/`
- K / q (Arthur Whitney) — `https://en.wikipedia.org/wiki/K_(programming_language)`, `https://kx.com/`
- BQN (Marshall Lochbaum) — `https://mlochbaum.github.io/BQN/`
- Uiua (Tony Morris) — `https://www.uiua.org/`, `https://github.com/uiua-lang/uiua`

**Cluster 3 — Intent-Mapping:**
- Jofito (Jody Bruchon) — `https://codeberg.org/jbruchon/jofito` (README 2026 UPDATE NOTE: "intent mapping engine"), `docs/transcripts/Ddme7DwMQBI_jofito_jody_bruchon.txt` (full video transcript, 428 lines)
- jq (Stephen Dolan) — `https://en.wikipedia.org/wiki/Jq_(programming_language)`, `https://jqlang.org/`
- nagent's tag protocol — `conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md` (lines 210-230 for the Bridge DSL), `decisions.md` (line 50: user rejects XML/JSON; lines 117-134: Candidate 4: Intent-based DSL for Meta-Tooling)
- WebAssembly — `https://en.wikipedia.org/wiki/WebAssembly`

**Cluster 4 — Meta-Tooling DSLs:**
- `mcp_dsl_20260606` placeholder — `conductor/tracks/mcp_architecture_refactor_20260606/spec.md` §12.1 and §13.1 (per-MCP grammar, 8x token reduction, backward compat)
- nagent's Bridge DSL — `conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md` line 216-230
- OpenAI function-calling — `https://platform.openai.com/docs/guides/function-calling`
- Anthropic tool-use — `https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/define-tools`

**Cluster 5 — SSDL:**
- `docs/reports/computational_shapes_ssdl_digest_20260608.md` §1 (6 primitives + 7 modifiers)

**Cluster 7 — Result convention:**
- `conductor/tracks/data_oriented_error_handling_20260606/spec.md` §3.3 (Result[T], ErrorInfo, 12 ErrorKind values)

### A.2 Project's own references

**Existing tracks and reports:**
- `conductor/tracks.md` — active tracks registry
- `conductor/workflow.md` — the workflow rules (4-phase pattern, TDD, git notes)
- `conductor/product.md` — the product vision
- `conductor/tech-stack.md` — the tech stack constraints
- `conductor/code_styleguides/` — the styleguides (Python style, error handling, workspace paths, etc.)
- `docs/Readme.md` — the doc index
- `docs/ideation/ed_chunk_data_structures_20260523.md` — the existing ideation doc; same style/format as this report

**Per-source-file guides:**
- `docs/guide_architecture.md` — threading model, event system, HITL, telemetry
- `docs/guide_meta_boundary.md` — Application vs Meta-Tooling split
- `docs/guide_tools.md` — MCP Bridge security, 45 tools, Hook API, ApiHookClient
- `docs/guide_mma.md` — 4-tier Multi-Model Architecture
- `docs/guide_context_aggregation.md` — the 518-line `aggregate.py` pipeline (3 strategies, 7 view modes)
- `docs/guide_command_palette.md` — 33 commands, fuzzy search, "Everything" mode
- `docs/guide_rag.md` — opt-in RAG (ChromaDB)
- `docs/guide_state_lifecycle.md` — undo/redo, HistoryManager, state delegation
- `docs/guide_testing.md` — 251 test files, 7 conftest fixtures
- `docs/guide_personas.md` — persona management
- `docs/guide_workspace_profiles.md` — docking layout profiles

**Track-internal references (recent):**
- `conductor/tracks/data_oriented_error_handling_20260606/spec.md` — the Result[T] convention
- `conductor/tracks/nagent_review_20260608/nagent_review_v2_1_20260612.md` — 4 memory dimensions, RAG integration discipline, stable-to-volatile cache ordering
- `conductor/tracks/mcp_architecture_refactor_20260606/spec.md` — the SubMCP architecture (the target the DSL maps to)
- `conductor/tracks/code_path_audit_20260607/spec.md` — the data-oriented pattern for static analysis

**Reports:**
- `docs/reports/computational_shapes_ssdl_digest_20260608.md` — SSDL 6 primitives + 7 modifiers
- `docs/reports/ascii_sketch_ux_workflow_20260608.md` — the user's ideation workflow convention

### A.3 Sub-reports (the research basis for §2)

- `research/cluster_0_odonnell.md` (338 lines) — Cluster 0 synthesis
- `research/cluster_1_concatenative.md` (209 lines) — Cluster 1 synthesis
- `research/cluster_2_array.md` (218 lines) — Cluster 2 synthesis
- `research/cluster_3_intent_mapping.md` (241 lines) — Cluster 3 synthesis
- `research/cluster_4_meta_tooling_dsls.md` (313 lines) — Cluster 4 synthesis
