Decline [2.9]: the opaque TypeScript AST handles are the boundary working

Raised off "low priority" earlier today so it could be CONSIDERED rather than
deferred again. Considered; the answer is no, on the merits.

The gap is real but has no consumer. index.d.ts is 1,169 hand-written lines and
already rich for everything the facade returns; only the 19 branded node handles
are structureless. riddl-vscode -- the TypeScript consumer -- calls
parseToTokens 14x, parseString 11x, getTree, validateString, inspectRoot,
getMessageFlow and getHandlerCompleteness, and touches a raw AST handle ZERO
times. An editor extension wants highlighting, diagnostics and an outline, and
the facade serves all three. The consumer that genuinely walks the AST is
Synapify, which is Scala.js and has the real objects with their methods.

What settled it was measuring the proposed implementation rather than arguing
about it. Generating the .d.ts from JsonModel sounds economical -- JSON is
already a complete, gated, zero-divergence surface -- but JSON serializes STATE
and this AST's value is substantially BEHAVIOUR. AST.scala carries ~540
def/lazy val members that do not serialize: 182 `format`, 67 `kind`, the 34
WithX accessor traits, and derived answers like effectiveShape,
Connector.isPersistent (which accepts both spellings), Statement.canFail,
NumericLiteral.asLong and Function.input/output. JsonModel has zero references
to refMap, symTab or usedBy, so no resolution output crosses at all.

The disqualifying detail is smaller and worse: JSON preserves Include and
BASTImport as CONTENT ENTRIES, so a TypeScript consumer walking `contents` sees
the wrapper rather than through it. That is precisely the defect that had
riddl-generator emit 582 files for reactive-bbq with no entity class among
them, at exit 0. A JSON-derived TS AST would not be "the AST minus methods" --
it would be an AST that invites every consumer to reimplement
include-transparency and alias resolution, which is the pair two separate
consumers have already got wrong.

It would also add a fifth reflective surface to keep in lockstep with parse,
prettify, BAST and JSON, for a consumer population of zero, and nothing would
fail when it drifted.

Recorded in CLAUDE.md so the next session does not re-propose it. If it ever
returns the trigger is DEMAND, not opacity: a TS consumer hits a wall the facade
cannot answer, and the facade gains one accessor inside the conversion layer.

BACKLOG is now down to a single open item, [0.2], which is blocked by design
until 2.0.0 exists.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: reid-spencer

BACKLOG.md

@@ -1722,14 +1722,40 @@ that needs a ruling before either can be fixed.
   from A23's `isEffectStatement` — `set` is an effect but cannot fail — and value-level
   failure points are deliberately counted separately rather than folded into the predicate.
 
-- **[2.9]** TypeScript AST declarations for the JS side. **NO LONGER LOW PRIORITY**
-  (Reid, 2026-08-27) — the "low priority, file it, do not schedule it" framing came from
-  NOTEBOOK's Active Work Queue and no longer holds. The full AST hierarchy (Domain, Context,
-  Entity, …) is still OPAQUE to TypeScript; only the public `RiddlAPI` methods are declared,
-  so a JS consumer wanting the AST itself gets a branded `RootAST` and no structure. The old
-  justification was that consumers are *expected* to use the facade — which is an argument
-  about what we intended, not about what consumers need, and it is the same shape as
-  [1.20]: a surface we did not wire is not the same fact as a surface nobody wants.
+- ~~**[2.9]** TypeScript AST declarations for the JS side.~~ — **DECLINED 2026-08-27**, on
+  the merits, after being raised off "low priority" the same day so it could be *considered*
+  rather than deferred again. Considered, and the answer is no.
+  **The opaque `*AST` handles are a BOUNDARY DOING ITS JOB, not a gap.** `index.d.ts` is 1,169
+  hand-written lines and already rich for everything the facade returns — `RiddlResult`,
+  `Token`, `ValidationResult`, `OutlineEntry`, `TreeNode`, `MessageFlowEdge`, the whole
+  `RiddlAPI`. Only the 19 branded node handles (`RootAST`, `EntityAST`, …) are structureless.
+  **There is no consumer for the missing part.** riddl-vscode — the TypeScript consumer —
+  calls `parseToTokens` (14×), `parseString` (11×), `getTree`, `validateString`, `inspectRoot`,
+  `getMessageFlow`, `getHandlerCompleteness`, and touches a raw AST handle **zero times**. An
+  editor extension wants highlighting, diagnostics and an outline; the facade serves all three.
+  The consumer that genuinely walks the AST is **Synapify, which is Scala.js and has the real
+  thing, methods included** (Reid: *"most users are going to use it from Scala.js where we have
+  mechanisms in place"*).
+  **The proposed implementation — generate the `.d.ts` from `JsonModel` — was measured and is
+  WORSE than it sounds, which is what settled it.** JSON serializes STATE; the AST's value is
+  substantially BEHAVIOUR. `AST.scala` carries **540 `def`/`lazy val` members**, none of which
+  serialize: 182 `format`, 67 `kind`, the **34 `WithX` accessor traits**, and derived answers
+  like `effectiveShape`, `Connector.isPersistent` (which accepts both spellings),
+  `Statement.canFail`, `NumericLiteral.asLong`, `DoStatement.text`, `Function.input`/`output`.
+  `JsonModel` also contains **zero** references to `refMap`, `symTab` or `usedBy`, so no
+  resolution output crosses at all.
+  **The disqualifying detail**: JSON preserves `Include`/`BASTImport` as CONTENT ENTRIES, so a
+  TypeScript consumer walking `contents` sees the WRAPPER rather than through it. That is
+  exactly the defect that had riddl-generator emit 582 files for reactive-bbq with no entity
+  class among them, at exit 0. A JSON-derived TS AST would not be "the AST minus methods" — it
+  would be an AST that INVITES every consumer to reimplement include-transparency and
+  alias-resolution, the two things two separate consumers have already got wrong (see
+  [1.20]'s two incidents).
+  **It would also add a FIFTH reflective surface** to keep in lockstep with parse, prettify,
+  BAST and JSON, for a consumer population of zero — and nothing would fail when it drifted.
+  **If this ever comes back, the trigger is DEMAND, not opacity**: a TS consumer hits a wall the
+  facade cannot answer, and the facade gains one accessor, inside the conversion layer. Do not
+  export the AST.
 
 - ~~**[2.10]** Repo housekeeping — three items.~~ — **ALL THREE DONE 2026-08-27**, on
   Reid's explicit go-ahead, which was the only thing the entry had been waiting on.

CLAUDE.md

@@ -2493,6 +2493,27 @@ validation — resolution and type-checking — in `checkStatementScopes`.
   enforces it.
 - **npm prerelease publishing** — sbt-dynver versions like
   `1.2.3-1-hash` are prerelease per npm semver; pass `--tag dev`.
+- **The opaque `*AST` handles in `index.d.ts` are DELIBERATE. Do not "fix" them by exporting
+  the AST to TypeScript** (considered and DECLINED 2026-08-27, BACKLOG [2.9]). `parseString`
+  hands JS a branded handle (`RootAST`, `EntityAST`, …) that can only be passed back in;
+  structure is served through flattened projections (`inspectRoot`, `getOutline`, `getTree`).
+  Three reasons, in order of weight:
+  1. **JSON serializes STATE; the AST's value is largely BEHAVIOUR.** `AST.scala` carries ~540
+     `def`/`lazy val` members that do not serialize — 182 `format`, 67 `kind`, the 34 `WithX`
+     accessor traits, and derived answers like `effectiveShape`, `Connector.isPersistent`,
+     `Statement.canFail`, `Function.input`/`output`. `JsonModel` has ZERO references to
+     `refMap`/`symTab`/`usedBy`, so no resolution output crosses either.
+  2. **JSON keeps `Include`/`BASTImport` as content entries**, so a consumer walking `contents`
+     sees the WRAPPER rather than through it — the exact defect that had riddl-generator emit
+     582 files with no entity class, at exit 0. A JSON-derived TS AST would invite every
+     consumer to reimplement include-transparency and alias-resolution.
+  3. **It would be a FIFTH reflective surface** to keep in lockstep with parse/prettify/BAST/
+     JSON, and nothing would fail when it drifted.
+  **The real consumers agree**: riddl-vscode touches a raw AST handle zero times (all facade —
+  `parseToTokens`, `parseString`, `getTree`, `validateString`, …), and the consumer that truly
+  walks the AST is Synapify, which is **Scala.js and has the real objects, methods included**.
+  If this returns, the trigger is a TS consumer hitting a wall the facade cannot answer — add
+  one accessor inside the conversion layer, never the AST.
 - **NEVER `@JSExport` an overridden `toString`.** Interpolation compiles to JS
   `+`, so `s"…$loc…"` throws `TypeError: Cannot convert object to primitive
   value` and takes down the whole validation run on JS while the JVM passes.