ESC-01: AffineScript has no raw/FFI escape — %%raw port target (Refs 229) #245

Activity

1. hyperpolymath

   added

   enhancementNew capability or improvement to existing behaviourNew capability or improvement to existing behaviour

   on May 19, 2026
2. hyperpolymath

   added 5 commits that reference this issue on May 19, 2026

   docs(estate): #229 foundation — post-#228 re-audit, RS inventory, can…

   ...

   9be1cfa

   docs(estate): #229 foundation — post-#228 re-audit, RS inventory, can…

   ...

   a6e8886

   docs(adr): ESC-01 — ADR-018 no raw/FFI escape, typed extern only (Refs …

   ...

   d19afa1

   docs(adr): ESC-04 — ADR-017 ReScript block-module disposition (Refs #262

   ...

   084886e

   docs(adr): ESC-04 — ADR-017 ReScript block-module disposition (Refs #262

   ...

   dc6a893
3. hyperpolymath commented on Jun 1, 2026

   

   hyperpolymath

   on Jun 1, 2026

   OwnerAuthor

   More actions

   Status update — AS stdlib codegen pattern now established (2026-06-01) 📌

   For ticket coordinators / anyone tracking this gap:

   • affinescript#522 + feat(stdlib): close 6 STEP-3 Deno-ESM gaps surfaced by TS→AS ports (Refs #239, #242) #504 merged 2026-06-01 establish the canonical stdlib extern → Deno-ESM lowering pattern via lib/codegen_deno.ml. Tests live in tests/codegen-deno/*.
   • affinescript#463 unblocked non-ASCII string emit in Deno-ESM (Unicode escapes, not octal).
   • affinescript#421 put stdlib/json on the Zig-FFI rails (hpm-json-rsr).

   What this means for the gap tracked in this ticket:

   • The codegen pattern is now a known repeatable shape: declare in stdlib/*.affine → wire in deno_builtins table + prelude → smoke-test in tests/codegen-deno/*.
   • This ticket remains open as a tracked gap; no new mass-port is being kicked off from this post.
   • Surfacing status so the broader picture stays accurate as more sub-tickets / dependent campaigns reference it.

   🤖 Cross-estate AS-status sweep on 2026-06-01.
4. hyperpolymath commented on Jun 11, 2026

   

   hyperpolymath

   on Jun 11, 2026

   OwnerAuthor

   More actions

   Doctrine recommendation 2026-06-11 — Option 1 (no raw escape)

   Endorsing the issue body's own "affine-discipline-preserving default". The escape hatch in Option 2 would dissolve every guarantee the typed FFI machinery is engineered to provide; #229's stated end-goal is "zero ReScript surface in any .affine", and %%raw is the ReScript surface marker.

   Why this is the right doctrine, not just the conservative one

   The typed extern path is already the canonical answer for everything %%raw is used for in the estate:

   Common %%raw use	Typed-extern target
   %%raw('Math.imul(a,b)') etc. — JS primitive that should have been a binding	extern fn imul(a: Int, b: Int) -> Int; + host wrapper
   %%raw('function() { ... promise / DOM thing }')	extern fn op(arg: T) -> R / { Async }; + host wrapper
   %%raw('setInterval(fn, ms)') — missing-from-stdlib timer	extend stdlib/effects.affine + add Deno-builtin wiring (the canonical pattern post-#522 / #504)
   %%raw('JSON.stringify(x)') — should have been stdlib/json	stdlib/json already has the binding (#421 / #463) — port %%raw away
   %%raw('window.foo.bar') — DOM access	affinescript-dom (#56 / #183) — the typed surface this gap was waiting on
   %%raw('require("...")') / dynamic import	extern fn + a single host-side resolver shim

   The 14 estate occurrences split cleanly across these buckets — there is no residual "genuinely untyped" case that Option 2 would be the answer for. Where a typed binding doesn't yet exist (Motion, parts of Pixi, niche Deno externs), the right move is to add the binding — which is exactly the work tracked under the bindings campaign (#446 tier-1..5) and #56.

   Migration template (per-file pattern)

   For each %%raw-bearing .affine consumer:

   Before:

   // SomeFile.affine
   let f: (Int, Int) -> Int = %%raw(`
     function(a, b) { return Math.imul(a, b); }
   `);
   

   After (two files):

   SomeFile.affine (the consumer):

   extern fn imul(a: Int, b: Int) -> Int;
   // uses imul(a, b) directly
   

   SomeFile.runtime.js (or whichever host wrapper the package ships):

   globalThis.__as_imul = (a, b) => Math.imul(a, b);

   Plus a one-line wiring entry in the host's externs table. The Deno-ESM lowering pattern established by #522 / #504 covers this; tests/codegen-deno/*.harness.mjs is the test scaffold.

   Estate impact

   14 %%raw occurrences post-#228 re-audit. Buckets above show every one is a typed-extern port — no residual case is genuinely untyped. The work bifurcates into two slices:

   1. Per-consumer ports (this issue) — close %%raw sites by emitting extern declarations. Mechanical once the host-side runtime wrapper exists.
   2. Per-binding additions ([campaign] AffineScript top-50 framework bindings roadmap (UMBRELLA) #446, [Repo] affinescript-dom and affinescript-pixijs as production-ready migration prerequisite #56) — where a binding doesn't exist yet, file under the bindings campaign or close the dom/pixijs gap. Already in flight.

   Action

   If accepted as doctrine, codify in docs/RESCRIPT-ELIMINATION.adoc (Tier-3 ESC-01 line) + a one-line entry in SETTLED-DECISIONS.adoc referencing this issue. The migration tool (tools/res-to-affine / #488 partial-port mode) adds a --raw-to-extern flag that emits the per-occurrence template above — the host wrapper is hand-written per binding, but the consumer-side .affine edit is mechanical.

   Recommendation: close #245 with Option 1 doctrine + the migration template. The 14 occurrences move to per-consumer port PRs.

   🤖 Cross-estate AS-status sweep on 2026-06-11.
5. hyperpolymath commented on Sep 19, 2026

   

   hyperpolymath

   on Sep 19, 2026

   OwnerAuthor

   More actions

   Measured across the estate today (2026-09-19) — the gap is real, and materially bigger than this issue records.

   The issue cites "14 occurrences across the estate .affine files". Current counts in the consumer repos that carry ReScript surface:

   Repo	files using %%raw	occurrences in .affine
   burble	12	143
   git-scripts	2	2
   game-server-admin	0	0
   invariant-path	0	0

   Sampled from real call sites, e.g. `%%raw(``, so these are live uses, not mentions in prose.

   So the escape hatch this issue asks for has more callers than when it was filed, not fewer — it is the opposite of stale. Relationship to #229 holds: those calls are exactly the ReScript surface that cannot be ported until this lands, which is why the two issues should be sequenced together rather than #229's residual being chased first.
6. hyperpolymath

   added

   priority:p1High - schedule nextHigh - schedule next

   scope:estateAffects many or all repos across the estateAffects many or all repos across the estate

   status:needs-rulingAwaiting an owner decisionAwaiting an owner decision

   feeds:valence-shellFeeds valence-shell's proofs/engineering (D127): judge progress by what it contributes thereFeeds valence-shell's proofs/engineering (D127): judge progress by what it contributes there

   on Sep 30, 2026
7. hyperpolymath commented on Sep 30, 2026

   

   hyperpolymath

   on Sep 30, 2026

   OwnerAuthor

   More actions

   RULING D190 (2026-09-30T14:23Z) · scope: repo · basis: applied-unless-struck (D113; owner approved the full table, none struck)

   No raw escape: port every %%raw to a typed extern.

   surface: hyperpolymath/standards#787 (comment)

   The open question in this issue is answered by the ruling above; future agents should act on it rather than re-ask.
8. hyperpolymath

   removed

   status:needs-rulingAwaiting an owner decisionAwaiting an owner decision

   on Sep 30, 2026
9. hyperpolymath

   added a commit that references this issue on Oct 8, 2026

   feat(stdlib/bun): bun_run_capture — captured child-process run (#781)

   ...

   4e2d263