# Intent-Based Scripting Languages

**Track:** `intent_dsl_survey_20260612` (initialized 2026-06-12)
**Date:** 2026-06-12
**Author:** Tier 1 Orchestrator (sections 1, 3, 4, 5, 6, 7, Appendix); Tier 2 sub-agents (section 2 clusters 0, 1, 2, 3, 4)
**Status:** Outline draft (phase 1 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.

---

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

*[STUB: 4 anchor claims — O'Donnell immediate-mode as the philosophical anchor; Onat/Lottes hardware-pipeline model as the truth the verbs must map to; CoSy open-vocabulary culture as the user-surface principle; Jofito intent-mapping as the framing that names the design philosophy. ~2-3 pages.]*

## 2. Prior Art Survey (8 Clusters)

This section surveys the design lineage across 8 clusters. Each entry: 2-3 sentences on the design idea, 2-3 sentences on what we take from it (or, in cluster 3, what we explicitly reject). Every entry cites a specific source.

### Cluster 0 — Immediate-Mode Paradigm (philosophical anchor)
*[STUB: John O'Donnell's IMGUI/MVC essays. ~0.5-1 page.]*

### Cluster 1 — Concatenative (Forth family)
*[STUB: Forth, ColorForth, KYRA/Onat, x68/Lottes, Joy, CoSy. ~1-1.5 pages.]*

### Cluster 2 — Array
*[STUB: APL, K, BQN, Uiua. ~0.5 page.]*

### Cluster 3 — Intent-Mapping
*[STUB: Jofito, jq, nagent's tag protocol (REJECTED as a model — we take the structured-protocol idea but not the XML angle brackets), Wasm. ~0.5-1 page.]*

### Cluster 4 — Meta-Tooling DSLs and Agent-Facing Languages
*[STUB: mcp_dsl_20260606 placeholder, nagent's Bridge DSL, OpenAI function-calling, Anthropic tool-use. ~0.5 page.]*

### Cluster 5 — SSDL Shape Primitives
*[STUB: 6 primitives + 7 modifiers per `docs/reports/computational_shapes_ssdl_digest_20260608.md` §1. The meta-vocabulary used to annotate the verbs in section 4. ~0.25 page.]*

### Cluster 6 — Project's Own Command DSL Precedents
*[STUB: the 33 Command Palette commands per `docs/guide_command_palette.md` and `src/commands.py`. The DSL is a richer superset; "Everything" mode is a near-term use case. ~0.25 page.]*

### Cluster 7 — Data-Oriented Error Handling Convention
*[STUB: `Result[T]` + `ErrorInfo` per `conductor/tracks/data_oriented_error_handling_20260606/spec.md` §3.3. The DSL's `try`/`recover`/`sandbox`/`didyoumean` verbs return `Result[T]`. ~0.25 page.]*

## 3. The Grammar

*[STUB: 14 primitives formalized from the user's math pseudocode (`determinate`/`minor`/`matrix-transpose` snippets). Each primitive: symbol, name, signature, one-line semantics, example, "borrowed from" note. Plus 3 known ambiguity flags (`proc` placement, `++` → `+= 1`, `m[row][column]` → `m[row, col]`). Plus precedence rules (left-to-right for `->` chains, `()` for grouping) and AI-fuzzing tolerance rules (CoSy-style modulo indexing, structured recovery anchors via `{}`, line/offset independence). Plus the error envelope (`try { ... } recover { ... }` returns `Result[T]`). ~2-3 pages.]*

## 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 1 — Math (~10 verbs)
*[STUB: from the user's pseudocode. `:=`, `stack { }`, `for x .. n`, `+`, `-`, `*`, `/`, `^`, `sum`, `product`, `a[i,j]`, `if/then`.]*

### Tier 2 — Data-Oriented Pipeline (~12 verbs)
*[STUB: Onat/Lottes/Jofito lineage. `scan`, `select`, `filter`, `map`, `fold`, `sort`, `group`, `dedupe`, `arena { }`, `scatter`, `gather`, `pipe`. The verbs that wrap the existing 45+ MCP tools.]*

### Tier 3 — Shell (~10 verbs)
*[STUB: the OS surface. `exec`, `open`, `read`, `write`, `close`, `path`, `env`, `wait`, `poll`, `cwd`.]*

### Tier 4 — AI-Fuzzing Tolerance (~8 verbs — the novel contribution)
*[STUB: the verbs that make the DSL work for AI agents that may fuzz verb names, indent inconsistently, or offset line references. `fuzzy`, `try { ... } recover { ... }`, `sandbox { ... }`, `audit`, `didyoumean`, `span`, `offset`, `assumewide`. The `sandbox` verb is O'Donnell's IEventTarget pattern applied to the DSL; the `audit` verb is the IEventTarget itself.]*

## 5. Hardware Mapping (4 Anchor Claims)

*[STUB: 4 anchor claims tying the vocab to actual hardware/software stages.*

1. **Onat/Lottes, hardware:** the 2-register stack + magenta pipe + basic blocks + lambdas + preemptive scatter (per `C:\projects\forth\bootslop\references\kyra_in-depth.md`, `forth_day_2020_in-depth.md`, `neokineogfx_in-depth.md`, `X.com - Onat & Lottes Interaction 1.png.ocr.md`) → our `->`, `[ ]`, `arena { }`, `scatter`/`gather`.
2. **O'Donnell, paradigm:** the DSL's pipeline is *immediate-mode in pipeline composition*. Per `https://johno.se/book/imgui.html`. The `->` chain has no "pipeline object" you can query, name, or pass around.
3. **Forth/CoSy, syntax:** concatenative syntax is immediate-mode in tokenization (whitespace-delimited, no precedence), evaluation (each verb pops args, pushes results), and parsing (no AST object retained after parse).
4. **APL/K, data:** array languages are immediate-mode in data representation. The DSL's `for x .. n` + `result[row, col]` inherits the "no array object" property.

*~1-2 pages.]*

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

*[STUB: 10 claims tying the DSL to the existing project's architecture so future tracks can build on it without re-deriving the design.*

1. Domain = Meta-Tooling (per `docs/guide_meta_boundary.md`).
2. Runtime path = external agent → DSL text → bridge script → MCP → optional Hook API approval (per `docs/guide_meta_boundary.md` §"The Inter-Domain Bridges").
3. 3-layer security (per `docs/guide_tools.md` §"The MCP Bridge"): the parser rejects DSL statements that target tools outside the allowlist.
4. 4 memory dimensions (per `conductor/tracks/nagent_review_20260608/nagent_review_v2_1_20260612.md` §2.1): the DSL does not replace any memory dimension.
5. Stable-to-volatile cache ordering (per nagent v2.1 §2.2): the DSL's `arena { }` blocks are cache-friendly.
6. `Result[T]` envelope (per `conductor/tracks/data_oriented_error_handling_20260606/spec.md`): `try`/`recover` verbs return `Result[T]`.
7. Command Palette 33 commands (per `docs/guide_command_palette.md`): the DSL is a richer superset; "Everything" mode is a near-term use case.
8. Hook API state fields (per `docs/guide_state_lifecycle.md` §"Hook API Surface"): DSL verbs route through `_predefined_callbacks` and `_gettable_fields`.
9. O'Donnell's IEventTarget pattern as the `sandbox` verb (per `https://johno.se/book/mvc.html` §"Writing to Model state").
10. O'Donnell's "reads are free" claim (per `https://johno.se/book/mvc.html` §"Reading Model state"): Tier 2 verbs are read-only and re-evaluable.

*~2-3 pages.]*

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

*[STUB: open questions that the follow-up B track (interpreter prototype) must answer, plus the connection block to the `intent_dsl_for_meta_tooling_20260608_PLACEHOLDER`.*

1. How does `arena { }` map to Onat's preemptive scatter? Block-as-tape vs wrapper-allocates-tape?
2. Where does "intent resolution" live? Per-verb option, per-block modifier, or global parser mode?
3. How does `audit` interact with Manual Slop's existing `comms.log`? Separate JSON-L or merged?
4. Does `sandbox` produce `Result[T, ErrorInfo]` (Fleury pattern)?
5. `didyoumean` recovery: parser feature or user-facing verb?
6. How does `for x .. n` interact with Tier 2's `filter`/`map`? Sugar or distinct?
7. How does `sandbox` map to Manual Slop's `pre_tool_callback` flow? New audit log or fold into existing?
8. Connection to `intent_dsl_for_meta_tooling_20260608_PLACEHOLDER`: minimum vocab subset for one round-trip end-to-end?

*~1-2 pages.]*

---

## Appendix: Bibliography

*[STUB: full file:line / URL references for all 8 prior-art clusters + the project's own references. Grouped by cluster. Each entry: 1 line with the source identifier and the file:line or URL.]*