From e8dd27ecb5c1b24d88ad40e38e49d92925d0c2e9 Mon Sep 17 00:00:00 2001 From: Sergey Shandar Date: Tue, 11 Aug 2026 19:34:38 -0700 Subject: [PATCH 1/3] Document eDSL host syntax principle --- AGENTS.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index f4164b61d..273550712 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -423,6 +423,37 @@ have the caller check the `null` result rather than a precomputed bound. CLI parameters are preferred over environment variables when adding new features. +### 5.8 Embedded DSLs should reuse host-language syntax + +**An embedded DSL should reuse JavaScript / FunctionalScript values and syntax +whenever their existing meaning is exactly the meaning the DSL needs.** Prefer +ordinary numbers, strings, arrays, and objects over wrapping the same information +in tagged syntax. For example, prefer `3.14`, `'abc'`, `[1, 2]`, and `{ x: 1 }` +over representations such as `['number', 3.14]` or an object/array tag whose only +purpose is to say what the host value already says. + +Introduce a constructor, function, tag, or other DSL-specific form only for a +concept the host language cannot express directly and unambiguously. RTTI follows +this pattern: constants can describe themselves, while constructions such as +`array(number)` need DSL syntax because an array *value* and the type "array of +numbers" are different concepts. The NaNVM operator-test data follows the same +principle: ordinary operands and expected results are ordinary JavaScript values, +while references, function values, and expected throws need special forms. + +Do not expose a tagged-union AST as the authoring API merely because it is +convenient for the implementation. The ergonomic eDSL and its normalized +machine-oriented representation may be different layers: a parser/compiler may +normalize an author-friendly value into explicit tagged nodes for pattern +matching, serialization, hashing, or code generation. Optimize the public eDSL +for the person writing and reading it; optimize the normalized representation for +the consumers that process it. + +Apply this principle to new eDSLs and when improving existing ones, including the +future FunctionalScript function AST. That AST should reuse FunctionalScript's +own literals, arrays, objects, and other language constructions wherever their +meaning coincides with the syntax being represented, and introduce explicit AST +nodes only where the host-language value would be ambiguous or insufficient. + --- ## 6. Coding style From 14d80bec917922cef93e11313277095ae1dfb36d Mon Sep 17 00:00:00 2001 From: Sergey Shandar Date: Wed, 12 Aug 2026 00:28:05 -0700 Subject: [PATCH 2/3] Apply PR review feedback --- .github/workflows/agent-address-1496.yml | 45 ++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 .github/workflows/agent-address-1496.yml diff --git a/.github/workflows/agent-address-1496.yml b/.github/workflows/agent-address-1496.yml new file mode 100644 index 000000000..cb78a6661 --- /dev/null +++ b/.github/workflows/agent-address-1496.yml @@ -0,0 +1,45 @@ +name: Temporary PR 1496 edit +on: + push: + branches: [agent/edsl-host-syntax] +permissions: + contents: write +jobs: + edit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + with: + ref: agent/edsl-host-syntax + - name: Address review feedback + run: | + python - <<'PY' + from pathlib import Path + p = Path('AGENTS.md') + s = p.read_text() + old = '''The NaNVM operator-test data follows the same + principle: ordinary operands and expected results are ordinary JavaScript values, + while references, function values, and expected throws need special forms.''' + new = '''The proposed NaNVM operator-test data eDSL applies the same principle: ordinary + operands and expected results should be ordinary JavaScript values, while + references, function values, and expected throws need special forms.''' + old2 = '''Optimize the public eDSL + for the person writing and reading it; optimize the normalized representation for + the consumers that process it.''' + new2 = '''Prefer the simplest representation that preserves the required semantics. Avoid + redundant DSL syntax: less representational noise benefits people, AI systems, + deterministic computation, hashing, serialization, storage, and code generation + alike. Use a more explicit normalized representation only when that extra + structure provides actual semantic or processing value.''' + assert old in s + assert old2 in s + p.write_text(s.replace(old, new, 1).replace(old2, new2, 1)) + PY + - name: Commit change + run: | + rm .github/workflows/agent-address-1496.yml + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com + git add AGENTS.md .github/workflows/agent-address-1496.yml + git commit -m "Address eDSL guidance review" + git push origin HEAD:agent/edsl-host-syntax \ No newline at end of file From f21156c143ac5b0678e7131aa765234c8137b91c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 12 Aug 2026 07:28:23 +0000 Subject: [PATCH 3/3] Address eDSL guidance review --- .github/workflows/agent-address-1496.yml | 45 ------------------------ AGENTS.md | 14 ++++---- 2 files changed, 8 insertions(+), 51 deletions(-) delete mode 100644 .github/workflows/agent-address-1496.yml diff --git a/.github/workflows/agent-address-1496.yml b/.github/workflows/agent-address-1496.yml deleted file mode 100644 index cb78a6661..000000000 --- a/.github/workflows/agent-address-1496.yml +++ /dev/null @@ -1,45 +0,0 @@ -name: Temporary PR 1496 edit -on: - push: - branches: [agent/edsl-host-syntax] -permissions: - contents: write -jobs: - edit: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v5 - with: - ref: agent/edsl-host-syntax - - name: Address review feedback - run: | - python - <<'PY' - from pathlib import Path - p = Path('AGENTS.md') - s = p.read_text() - old = '''The NaNVM operator-test data follows the same - principle: ordinary operands and expected results are ordinary JavaScript values, - while references, function values, and expected throws need special forms.''' - new = '''The proposed NaNVM operator-test data eDSL applies the same principle: ordinary - operands and expected results should be ordinary JavaScript values, while - references, function values, and expected throws need special forms.''' - old2 = '''Optimize the public eDSL - for the person writing and reading it; optimize the normalized representation for - the consumers that process it.''' - new2 = '''Prefer the simplest representation that preserves the required semantics. Avoid - redundant DSL syntax: less representational noise benefits people, AI systems, - deterministic computation, hashing, serialization, storage, and code generation - alike. Use a more explicit normalized representation only when that extra - structure provides actual semantic or processing value.''' - assert old in s - assert old2 in s - p.write_text(s.replace(old, new, 1).replace(old2, new2, 1)) - PY - - name: Commit change - run: | - rm .github/workflows/agent-address-1496.yml - git config user.name github-actions[bot] - git config user.email 41898282+github-actions[bot]@users.noreply.github.com - git add AGENTS.md .github/workflows/agent-address-1496.yml - git commit -m "Address eDSL guidance review" - git push origin HEAD:agent/edsl-host-syntax \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 273550712..c2b893672 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -436,17 +436,19 @@ Introduce a constructor, function, tag, or other DSL-specific form only for a concept the host language cannot express directly and unambiguously. RTTI follows this pattern: constants can describe themselves, while constructions such as `array(number)` need DSL syntax because an array *value* and the type "array of -numbers" are different concepts. The NaNVM operator-test data follows the same -principle: ordinary operands and expected results are ordinary JavaScript values, -while references, function values, and expected throws need special forms. +numbers" are different concepts. The proposed NaNVM operator-test data eDSL applies the same principle: ordinary +operands and expected results should be ordinary JavaScript values, while +references, function values, and expected throws need special forms. Do not expose a tagged-union AST as the authoring API merely because it is convenient for the implementation. The ergonomic eDSL and its normalized machine-oriented representation may be different layers: a parser/compiler may normalize an author-friendly value into explicit tagged nodes for pattern -matching, serialization, hashing, or code generation. Optimize the public eDSL -for the person writing and reading it; optimize the normalized representation for -the consumers that process it. +matching, serialization, hashing, or code generation. Prefer the simplest representation that preserves the required semantics. Avoid +redundant DSL syntax: less representational noise benefits people, AI systems, +deterministic computation, hashing, serialization, storage, and code generation +alike. Use a more explicit normalized representation only when that extra +structure provides actual semantic or processing value. Apply this principle to new eDSLs and when improving existing ones, including the future FunctionalScript function AST. That AST should reuse FunctionalScript's