docs(adr-015): settle the S4 / S5 / S6c numbering drift (#180)

The ADR's staged plan in META.a2ml and its mirrors in TECH-DEBT.adoc /
ECOSYSTEM.adoc / SETTLED-DECISIONS.adoc had drifted into a confused
state where S5 was described in two contradictory ways:

  * ADR-015 (canonical, META.a2ml): S5 = `wasi:filesystem` (unblocks
    INT-06). Original S4 wording: "native `wasi:clocks` + environment
    + argv via preview2, replacing the preview1 shims behind the
    component path."

  * TECH-DEBT + ECOSYSTEM (post-S4b): "Remaining: S5 (native preview2
    clocks/env/argv replacing the preview1 shims)" — i.e. the ledger
    had quietly re-purposed S5 to mean what the ADR's S4 originally
    promised, and pushed `wasi:filesystem` off the visible plan.

Root cause: what shipped as `S4a` (clock_now_ms) and `S4b`
(env_count, arg_count) did NOT fulfil the ADR's original S4 — those
slices emitted preview1 shims (clock_time_get, environ_sizes_get,
args_sizes_get) and rely on the preview1->preview2 adapter to bridge
to wasi:clocks / wasi:cli, instead of having codegen emit native
preview2 calls. That's a defensible choice (the bridging is free,
preview1 stays the default until S6c, source-to-source targets are
untouched), but it left the ADR's S4 wording untrue and pulled the
ledger into a half-baked S5-redefinition to compensate.

Resolution: amend ADR-015 to record what S4 actually shipped, restore
S5 = `wasi:filesystem` everywhere, and document the native-preview2
codegen cleanup as a bundled step inside S6c (since switching from
`wasi_snapshot_preview1.*` imports to `wasi:clocks/monotonic-clock` /
`wasi:cli/environment` / `wasi:sockets/tcp` calls only pays off once
preview2 is the default). The amendment is explicit — the ADR is
honest about the divergence rather than pretending it didn't happen.

Files:
- .machine_readable/6a2/META.a2ml (ADR-015 canonical): S4 rewritten
  to "DONE, preview1-shim, NOT native preview2"; S6c gains the
  native-preview2 bundled cleanup; consequences line corrected
  ("preview1 retained as the default through S6b; flip at S6c").
- docs/TECH-DEBT.adoc INT-03 row: "Remaining: S5 (filesystem) +
  S6c (flip + native cleanup bundle)" replaces the S5 = native-
  preview2 framing. Notes ADR-015 in META.a2ml is canonical.
- docs/ECOSYSTEM.adoc INT-03 row: same correction.
- docs/specs/SETTLED-DECISIONS.adoc staged-plan summary line:
  S4 / S5 / S6c restated to match the ADR.

No code changes; numbering only. The shipped S4a, S4b, S6a, S6b
slice labels in prior commit messages remain accurate — this commit
only changes how the *remaining* plan is described, plus the ADR's
historical record of S4.

Refs #180

Author: claude

.machine_readable/6a2/META.a2ml

@@ -985,8 +985,22 @@ Staged plan (ledger INT-03; each row = one gated PR):
   post-codegen step wraps it with the standard preview1->preview2
   adapter into a component; ownership section survival asserted;
   wasmtime component-run smoke. Codegen unchanged ⇒ reversible.
-- S4: native `wasi:clocks` + environment + argv via preview2 (wasmtime
-  host-testable), replacing the preview1 shims behind the component path.
+- S4 (DONE, slices S4a clock + S4b env_count/arg_count): on-demand
+  preview1 imports (`wasi_snapshot_preview1.clock_time_get`,
+  `environ_sizes_get`, `args_sizes_get`) via the Effect_sites
+  pre-scan, canonical-order indexing through
+  `ctx.wasi_func_indices`. NOTE divergence from this ADR's original
+  S4 wording ("native `wasi:clocks` + environment + argv via
+  preview2"): the slice shipped as preview1-shim, NOT native
+  preview2 calls. This is sufficient under the component path
+  because both adapters bridge the preview1 imports to
+  `wasi:clocks` / `wasi:cli` internally; switching the codegen
+  to emit `wasi:clocks/monotonic-clock@0.2.x.now()` directly only
+  pays off once preview2 is the default (deferred into S6c). The
+  ADR is amended here to record what actually shipped rather than
+  pretending S4 fulfilled the original wording. String accessors
+  (env_at/arg_at) need byte-level wasm IR (I32Load8U/I32Store8) for
+  buffer marshalling and remain a tracked follow-up.
 - S5: `wasi:filesystem` (open/read/write/close) — unblocks INT-06.
 - S6a (WIT export lifting, DONE): codegen emits a `_start : () -> ()`
   shim that calls `main` and drops its i32 result whenever a
@@ -1013,11 +1027,19 @@ Staged plan (ledger INT-03; each row = one gated PR):
   / network-address marshalling and remain a tracked follow-up
   alongside env_at/arg_at.
 - S6c: flip the default wasm target to component and demote the
-  preview1 stdout path to a named legacy target.
+  preview1 stdout path to a named legacy target. Bundled cleanup:
+  replace the on-demand preview1 shims emitted by S4a/S4b/S6b
+  (clock_time_get, environ_sizes_get, args_sizes_get,
+  sock_shutdown) with native preview2 calls
+  (`wasi:clocks/monotonic-clock`, `wasi:cli/environment`,
+  `wasi:sockets/tcp`) — this only pays off once preview2 is the
+  default, hence its placement here rather than as a standalone
+  pre-flip slice.
 """
 consequences = """
 - End-state is one-way (the component model becomes the canonical wasm
-  target) but reversible-in-progress: preview1 retained through S5.
+  target) but reversible-in-progress: preview1 retained as the default
+  through S6b; the flip happens at S6c.
 - S3..S6 are HARD-GATED on S2 (toolchain). Tracked as a follow-up
   issue; this is disclosed, not hidden.
 - typed-wasm ownership-section ABI is unchanged; the coordination

docs/ECOSYSTEM.adoc

@@ -242,10 +242,16 @@ wasmtime real-host invoke exits 0 on `net_shutdown(stdin, RDWR)`
 network-address marshalling — tracked alongside env_at/arg_at.**
 String accessors (env_at/arg_at) gated on a
 byte-level wasm-IR extension (I32Load8U/I32Store8 absent today)
-— tracked as the next slice before/with S5 filesystem. Remaining
-sub-slices: S5 (native clocks/env/argv via preview2), S6c
-(flip the default wasm target from preview1 → component). WIT
-world of record: `wit/affinescript.wit`
+— tracked as the next slice before/with S5. Remaining sub-slices
+(per ADR-015 canonical numbering in META.a2ml): S5 — bring up
+`wasi:filesystem` (open/read/write/close), which unblocks INT-06
+(server-side runtime profile); S6c — flip the default wasm
+target from preview1 → component, bundled with the optional
+native-preview2 cleanup that replaces the on-demand preview1
+shims emitted by S4a/S4b/S6b with direct `wasi:clocks` /
+`wasi:cli` / `wasi:sockets` calls (only pays off once preview2
+is the default, hence the bundling). WIT world of record:
+`wit/affinescript.wit`
 |INT-04 |Publish compiler + runtime to JSR (then npm) |#181 |runtime
 packaging READY (affine-js + affinescript-tea JSR dry-run green;
 manual-only `publish-jsr.yml`; docs/PACKAGING.adoc). INT-01 dep

docs/TECH-DEBT.adoc

@@ -220,9 +220,15 @@ regression; wasmtime real-host invoke exits 0 on
 `net_shutdown(stdin, RDWR)` (returns ENOTSOCK, dropped). Larger
 socket primitives (recv/send/accept) need byte-level wasm IR for
 buffer / network-address marshalling and remain a tracked
-follow-up alongside env_at/arg_at.** Remaining: S5 (native
-preview2 clocks/env/argv replacing the preview1 shims), S6c
-(flip the default wasm target from preview1 → component)
+follow-up alongside env_at/arg_at.** Remaining: S5
+(`wasi:filesystem` — open/read/write/close; unblocks INT-06
+server-side runtime), S6c (flip the default wasm target from
+preview1 → component, bundled with the optional native-preview2
+cleanup that replaces the on-demand preview1 shims emitted by
+S4a/S4b/S6b with direct `wasi:clocks` / `wasi:cli` /
+`wasi:sockets` calls — only pays off once preview2 is the
+default, hence the bundling). ADR-015 in META.a2ml is the
+canonical numbering — TECH-DEBT mirrors it.
 |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

docs/specs/SETTLED-DECISIONS.adoc

@@ -301,17 +301,25 @@ change; *S2* toolchain provisioning (`wasm-tools`, `wasm-component-ld`,
 `wac`) — ABSENT today, a hard gate on S3+; *S3* componentize on-ramp
 (codegen still emits core wasm; post-step wraps it via the standard
 preview1→preview2 adapter; ownership-section survival asserted; wasmtime
-component-run smoke); *S4* native `wasi:clocks`/environment/argv; *S5*
-`wasi:filesystem` (unblocks INT-06); *S6a* (WIT export lifting) codegen
-auto-emits a `_start : () -> ()` shim around a parameter-less `fn main()`
-so `tools/componentize.sh --command` (preview1→preview2 *command*
-adapter) produces a real `wasi:cli/run`-exporting component that any
-WASI 0.2 host can invoke; *S6b* (sockets on-ramp) the `net_shutdown`
-builtin lowers to `wasi_snapshot_preview1.sock_shutdown` and the
-command adapter bridges to `wasi:sockets/tcp` internally — recv/send/
-accept gated on the same byte-level wasm-IR follow-up as env_at/arg_at;
-*S6c* flip the default wasm target to component and demote preview1 to
-a legacy target.
+component-run smoke); *S4* (slices S4a clock + S4b env_count/arg_count)
+on-demand preview1 imports for `clock_time_get`, `environ_sizes_get`,
+`args_sizes_get` via the Effect_sites pre-scan — the ADR is amended in
+META.a2ml to record this as preview1-shim (NOT native preview2 as
+originally worded); both adapters bridge to `wasi:clocks`/`wasi:cli`
+internally, native-preview2 codegen is deferred into S6c since it only
+pays off once preview2 is the default; *S5* `wasi:filesystem`
+(open/read/write/close — unblocks INT-06); *S6a* (WIT export lifting)
+codegen auto-emits a `_start : () -> ()` shim around a parameter-less
+`fn main()` so `tools/componentize.sh --command` (preview1→preview2
+*command* adapter) produces a real `wasi:cli/run`-exporting component
+that any WASI 0.2 host can invoke; *S6b* (sockets on-ramp) the
+`net_shutdown` builtin lowers to `wasi_snapshot_preview1.sock_shutdown`
+and the command adapter bridges to `wasi:sockets/tcp` internally —
+recv/send/accept gated on the same byte-level wasm-IR follow-up as
+env_at/arg_at; *S6c* flip the default wasm target to component and
+demote preview1 to a legacy target, bundled with the optional
+native-preview2 cleanup that replaces the on-demand preview1 shims
+emitted by S4a/S4b/S6b with direct `wasi:*` calls.
 
 This decision is settled; do not reopen without amending the ADR. Full
 ADR in `.machine_readable/6a2/META.a2ml` (ADR-015); ledger INT-03 in