Skip to content

TECH-DEBT.adoc

Latest commit

 

History

History
222 lines (198 loc) · 10.5 KB

TECH-DEBT.adoc

File metadata and controls

222 lines (198 loc) · 10.5 KB
Raw

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

open (this PR adds where touched; full sweep tracked here)

DOC-05

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

open

DOC-06

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

open

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 residual — parser-gated (honest finding): NLL/region inference (Polonius); flow-sensitive escape via outer = &x; tighter quantity integration. These are not reachable unsoundnesses today — the surface to express them does not parse (&mut e, → &T, &-in-literal, bare block-statements), so the next move is the parser surface, then the analysis.

S1

pt1 #240 + pt2 return-escape DONE (Refs #177); pt2 residual parser-gated — 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 (PR3a/b/c merged; #234 generalises the recogniser)

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

open #161

STDLIB-03

Dict/Map keyed container

S2

open #162

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

#180 ADR-015 accepted (full Component-Model re-target, staged S1..S6); S3+ hard-gated on S2 toolchain (wasm-tools/wasm-component-ld)

INT-04

Publish to JSR/npm

S2

#181 packaging READY (dry-run green, manual workflow); owner-gated publish; compiler-binary = #260

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-05/06/09/10/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

planned (Stage E)

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.