Skip to content

TECH-DEBT.adoc

Latest commit

 

History

History
279 lines (255 loc) · 14.1 KB

TECH-DEBT.adoc

File metadata and controls

279 lines (255 loc) · 14.1 KB

AffineScript Coordination Ledger (TECH-DEBT)

Important

This is the durable coordination index for the AffineScript doc-truthing
ecosystem epic (issue #175). Sub-issues are the work units; this ledger is the critical path and the shared state across sessions/bots. ID classes: DOC (documentation truthing), CORE (compiler soundness/completeness), STDLIB, INT (ecosystem integration), SAT (satellite repos). Severity: S1 = substrate/blocking, S2 = important, S3 = polish. Reconstructed and made authoritative 2026-05-19 (it was cited by #175–183 / #228 / #177 but never committed). For the spine + contract see ECOSYSTEM.adoc; for readiness see CAPABILITY-MATRIX.adoc.
Table of Contents

Critical path (read first)

Stage A  CLOSED ───────────────────────────────────────────────┐
Stage B  CLOSED (#215; residual conflicts = ADR-012 won't-fix)  │
Stage C  CLOSED 2026-05-18 (#128/#135 stdlib AOT)               │
                                                                 ▼
Stage D  ACTIVE ── CORE-01 (#177)  ─┐                            (base lang
         ├─ INT-01 (#178) ──────────┼─ substrate, S1            complete)
         ├─ INT-02 (#179) ──┐       │
         ├─ INT-03 (#180)   │       │
         └─ INT-04 (#181) ◄─┘ (◄ INT-01)                         │
            ADR-014 (#228)  ── estate port unblocker, S1         │
                                                                 ▼
Stage E  planned ── typed-wasm convergence hardening
         (#234, #235, #225/#160 line, INT-12) ──► stable multi-producer ABI

The mandate’s order of operations: CORE-01 first (the one named base-language soundness gap; user decision 2026-05-19), then the INT substrate, then Stage E.

Section A — DOC (documentation truthing)

Tracks issue #176. Authoritative status lives in CAPABILITY-MATRIX.adoc; this section keeps it from re-drifting.

ID Item Status

DOC-01

CAPABILITY-MATRIX.adoc exists and overrides all other status docs

DONE 2026-05-19 (this PR)

DOC-02

ECOSYSTEM.adoc — spine + AS↔typed-wasm contract + satellites
INT-01..12

DONE 2026-05-19 (this PR)

DOC-03

TECH-DEBT.adoc — this ledger

DONE 2026-05-19 (this PR)

DOC-04

Authoritative banners on README/BACKEND-IMPLEMENTATION/ COMPILER-CAPABILITIES/ALPHA-1-RELEASE-NOTES

DONE in tree 2026-05-21 (banners present on all four; README internal drift on lines 25/614 also fixed — pointed both at CAPABILITY-MATRIX). MONITOR posture stays live via DOC-08/09

DOC-05

STATE.a2ml drift flagged (it mirrors, does not lead)

DONE in tree 2026-05-21 (authoritative-status-doc + drift-flag keys present in .machine_readable/6a2/STATE.a2ml; README "Documentation" section now also labels STATE.a2ml as the mirror)

DOC-06

ROADMAP.adoc Ecosystem Integration Track (INT-01..12) cross-links this ledger

DONE in tree 2026-05-21 (ROADMAP.adoc §"Status & contract" cross-links CAPABILITY-MATRIX + TECH-DEBT + ECOSYSTEM and names the INT-01..12 track)

DOC-07

Stage A–E definitions authoritative (were never committed)

DONE 2026-05-19 (ECOSYSTEM.adoc §The spine)

DOC-08

MONITOR rule: reject backend-breadth over-claims

DONE (Hypatia/ gitbot DOC-FORMAT)

DOC-09

MONITOR rule: reject "production-ready"/stdlib-% over-claims

DONE

MONITOR enforcement (DOC-08/09): any PR re-introducing backend-breadth, "production-ready", or stdlib-percentage over-claims must be rejected.

Section B — CORE (compiler soundness / completeness)

ID Item Sev Status

CORE-01

Borrow-checker Phase-3 — borrow-graph validation. Part 1 LANDED (PR 240, Refs #177, gate 263/263): BorrowOutlivesOwner emitted; shared-XOR-exclusive enforced at use sites (UseWhileExclusivelyBorrowed); ownership derived from the param type (TyOwn/TyRef/TyMut) — owned/ref/mut discipline now enforced from real parsed source (closed a latent hole); call-arg borrows temporary; ref-binding graph tracked. Part 2 — return-escape LANDED (Refs #177, gate 271→274): return e (or fn-tail) whose value is a reference rooted at a callee-owned binding (local or by-value/own param) is now BorrowOutlivesOwner (pt1 only saw block tails — return r slipped through); ref/mut params are caller-owned and not flagged (no over-rejection; full stdlib AOT green). 3 hermetic tests in "E2E Borrow Graph". Part 2 — &mut e parser surface LANDED (Refs #177, gate 278→281, zero Menhir conflict delta — 21 S/R + 1 R/R baseline held; AMP MUT e is unambiguous): the exclusive-borrow expression is now expressible, so the pt1 shared-XOR-exclusive rules (ConflictingBorrow/UseWhileExclusivelyBorrowed) are reachable from source for the first time (3 hermetic "E2E Borrow Graph" tests; &mut e typed/codegen’d like &e — exclusivity is a static borrow property). &-in-{ literals and bare block-statements already parse on main; → &T/&T type sigil deliberately not added — ref T/mut T keyword types already express reference types; a &T sigil is duplicate surface (ADR territory, not a soundness gap). Part 2 residual — now the analysis, not surface: NLL/region inference (Polonius) + flow-sensitive escape via outer = &x are now expressible (surface unblocked); the remaining work is the dataflow analysis itself.

S1

pt1 #240 + pt2 return-escape + &mut surface DONE (Refs #177); residual = NLL analysis — issue #177

CORE-02

Effect-handler dispatch on WasmGC (currently UnsupportedFeature; EH proposal or CPS). The #225 CPS line closes the async slice.

S2

partial (#225 line CLOSED PR1..PR3d+PR4; #234 generalises the recogniser — ADR-016 ACCEPTED, side-table typecheck→codegen, staged S1..S4; S1 done)

CORE-03

ADR-014: module-qualified type/effect path. Decision settled (both ./:: accepted, Pkg::Type canonical, .→:: for free via the ::-fold). Was the estate’s dominant parse blocker (525/1177 .affine). Grammar LANDED + MERGED (PR #241, Refs #228, zero Menhir conflict delta — 21 S/R + 1 R/R unchanged); ADR-014 recorded in META.a2ml + SETTLED-DECISIONS.adoc. Supersedes DRAFT #231.

S1

grammar merged (#241). Post-#228 estate re-audit DONE — true #229 scope is ~84 files/12 repos (not the 491 DRIFT; bulk is non-RS, out of contract); authoritative ledger + language-grounded canonical map + ESC-01..03 escalations: RESCRIPT-ELIMINATION.adoc

CORE-04

Traits: associated-type substitution, where-clause supertraits, coherence checking.

S2

partial

CORE-05

Dependent/refinement types: predicate reduction / SMT.

S3

parse-only

Section C — STDLIB

ID

Item

Sev

Status

STDLIB-AOT

All stdlib files compile resolve→typecheck→codegen, CI-gated

S1

CLOSED 2026-05-18 (#128/#135; test/test_stdlib_aot.ml)

STDLIB-01

Portable Http.fetch primitive

S2

DONE — #160 + #225 joint-closed. Deno-ESM (#226) + typed-wasm CPS line PR1..PR3d (#227/#233/#236/#237/#238/#266) all merged; ADR-013 delivery plan complete; convergence ABI shared w/ Ephapax

STDLIB-02

Portable Json primitive

S2

LANDED (Refs #161 #246): stdlib/json.affine — pure recursive Json ADT + encoders/decoders/ get_field/stringify, AOT-gated (#136, gate 278→279). Target-agnostic (no host dep); String→Json parse is the Http typed-boundary bridge (ADR-018), not a hand-rolled parser. Closes ESC-02 #246 (the #229 JSON.t target)

STDLIB-03

Dict/Map keyed container

S2

LANDED (Refs #162 #247): stdlib/dict.affine — keyed container over [(String, V)] (the json::JObject representation): empty/from_pairs/get/contains/size/ insert/set/remove/keys/values; AOT-gated (#136). Closes ESC-03 #247 (the #229 Dict.t target); unblocks the additive Http.affine headers→Dict upgrade

STDLIB-04

Residual extern builtins → real implementations

S3

open

Section D — INT (ecosystem integration)

Full table with blocked-by in ECOSYSTEM.adoc §INT-01..12. Substrate summary:

ID

Item

Sev

Status

INT-01

Cross-module WASM import emission (substrate). use Mod::{fn} / use Mod::* → real (import "Mod" "fn" …), callee exports the symbol, indices line up: PROVEN end-to-end (two separately-compiled .wasm link + execute, cross-call = 42) and regression-locked — hermetic structural test in the gate (271/271) + reproducible deno harness tests/modules/xmod-link/. Multi-file libraries via use Mod::{…} are shippable. Qualified-value path now wired: use Mod; (or use Mod as M;) + Mod.fn(x) resolves+typechecks — pure parse-boundary lowering Resolve.lower_qualified_value_paths (applied in parse_with_face; embedders bypassing it call it directly — the formatter is unaffected, so source Mod.fn is preserved on fmt); regression-locked (4 hermetic tests, "E2E Qualified Value #178"). Remaining (distinct, NOT this unit — a parser gap, not the resolver): Mod::fn(x) in expression position is a parse error (::-in-value-expr unwired; :: reserved for Type::Variant).

S1

use ::{}/::* + use Mod;/as-qualified Mod.fn(x) DONE (PR Refs #178); ::-in-expression a separate parser follow-up

INT-02

Host-agnostic loader bridge

S1

PROVEN + locked (Refs #179): packages/affine-js loader (SAT-02 fixed; Deno/Node/browser parity, multi-ns import object, ownership accessor); 14 unit tests via pinned deno task test + tests/modules/loader-bridge/ e2e on real compiler-emitted xmod wasm (closes INT-01↔INT-02). Unblocks INT-05/08/11

INT-03

WASI preview2 / host I/O

S1→S4b

#180 ADR-015 (full Component-Model re-target, S1..S6); S2 toolchain #251 closed; S3 componentize done; S4a (clock) + S4b (env_count, arg_count) DONE — on-demand preview1 imports via Effect_sites pre-scan, canonical-order indexing through ctx.wasi_func_indices; combo regression proves no collision. String accessors (env_at/arg_at) gated on byte-level wasm IR (I32Load8U/I32Store8 absent today) — tracked next slice. Real-host main-invoke = S6 (WIT export lifting). Next S5 (native clocks/env/argv)

INT-04

Publish to JSR/npm

S2

#181 packaging READY (dry-run green, manual workflow); compiler-binary distribution decided = ADR-019 (#260, Releases + thin Deno/JSR shim, staged S1..S4) — S1/S2/S3 merged (#283/#284/#285); S4 done — INT-10 closed (#282). First JSR publish landed 2026-05-20: @hyperpolymath/affinescript@0.1.2 LIVE (cross-runtime Deno+Bun+Node, MPL-2.0, sibling .d.ts for fast-check). @hyperpolymath/affine-js + @hyperpolymath/affinescript-tea remain dry-run-OK / not-yet-dispatched. Compiler version-string drift fixed via #297/#300 (single source of truth lib/version.ml + release.yml tag-time bake step — v0.1.1 binary now self-reports 0.1.1). Repo-wide SPDX surface relicensed PMPL-1.0-or-later → MPL-2.0 (#301/#304; PMPL preserved as the narrative-preferred licence in root LICENSE).

INT-07

affinescript-tea runtime

S2

#182 runtime + run loop shipped (TeaApp/parseTeaLayout, Linear-msg enforced); INT-01 cleared (#253)

INT-08

DOM reconciler

S2

#183 implemented + compiles; .as→.affine fixed; runtime blocked by #255 (wasm loop-codegen defect)

INT-10

affinescript-lsp distribution

S2

DONE end-to-end live (#282, ADR-019 S4): LSP resolves the compiler via AFFINESCRIPT_COMPILER → affinescript on PATH → the @hyperpolymath/affinescript shim (src/compiler.rs); no bespoke bundling; locate/exec smoke + resolution unit tests green. As of 2026-05-20 the shim is published on JSR (@hyperpolymath/affinescript@0.1.2) and pins all three v0.1.1 binaries by SHA256, so the shim resolution path actually executes end-to-end now (was code-correct but inert before today’s publish).

INT-05/06/09/11/12

ledger-only; filed when blocker closes

—

planned

Section E — SAT (satellite repos)

ID

Item

Sev

Status

SAT-01

affinescript-dom reconciler (skeleton → real)

S2

open (=INT-08)

SAT-02

packages/affine-js hardcoded path / env-only imports

S1

FIXED by INT-02 (Refs #179): Deno.readFile(url.pathname) replaced by host-agnostic readBytes; env-only import shape replaced by multi-namespace buildImportObject; mod.js consumes the loader. Proven + locked (see INT-02)

SAT-03

affinescript-tea runtime build-out

S2

open (=INT-07)

SAT-04

affinescript-cadre router runtime

S2

planned (=INT-09)

SAT-05

affinescript-pixijs migration prerequisite

S3

open #56

Stage E — typed-wasm convergence runway

ID

Item

Sev

Status

CONV-01

Estate-wide re-validation of the #199/#205 closure ABI (static → real wasm engine)

S2

open #235

CONV-02

Effect-threaded async-boundary detection (generalise the structural-conservative recogniser)

S2

open #234

CONV-03

#225/#160 convergence ABI matured to "shared with Ephapax"

S1

partial (PR3a/b/c merged)

CONV-04

Widen emitted-wasm enforcement beyond L7+L10 toward L1–6/L13–16

S2

L13 (module isolation, negative form) DONE — Tw_verify.verify_module_isolation (carrier-free, no ABI change). L1–6/L14–16 need a new carrier section = multi-producer ABI proposal (filed for typed-wasm; NOT unilateral). Rust-verifier mirror + C5.1 = cross-repo follow-ups

CONV-05

INT-12: AffineScript-emitted fixtures into typed-wasm crates/typed-wasm-verify/tests/cross_compat.rs (typed-wasm "C5.1")

S1

planned — coordinate Refs hyperpolymath/typed-wasm

Update protocol

  • One PR per ledger unit; Refs #N (never Closes on the #175 epic — only the owner closes it).

  • Every capability-affecting PR updates CAPABILITY-MATRIX.adoc and this ledger in the same change; STATE.a2ml mirrors after.

  • dune runtest --force must stay green (baseline 260, 2026-05-19).

  • typed-wasm ABI changes are multi-producer: coordinate with hyperpolymath/typed-wasm and hyperpolymath/ephapax.