From 8461acd5852fc68eda3e61dc52b2f310d4f9fc93 Mon Sep 17 00:00:00 2001
From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com>
Date: Tue, 19 May 2026 21:48:11 +0100
Subject: [PATCH] =?UTF-8?q?chore(toolchain):=20#251=20=E2=80=94=20provisio?=
 =?UTF-8?q?n=20the=20component-model=20toolchain=20(ADR-015=20S2)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

INT-03 ADR-015 S2 / issue #251: the WASM Component-Model toolchain was
absent, hard-gating ADR-015 S3+ (componentize on-ramp). Owner
authorised provisioning (2026-05-19).

- Installed + verified (rustc 1.95.0): wasm-tools 1.249.0,
  wasm-component-ld 0.5.22, wac-cli 0.10.0 (binary `wac`).
- `tools/provision-component-toolchain.sh` — the reproducible,
  committed deliverable: exact pinned versions + `cargo install
  --locked` (deterministic per pinned version via each crate's
  committed Cargo.lock), idempotent re-run. A guix.scm/flake.nix
  devShell entry is a tracked follow-up (the repo has neither yet;
  introducing one is out of #251's bounded scope — noted in the
  script header).
- ECOSYSTEM/TECH-DEBT INT-03 truthed: S2 done, **S3 unblocked**.

Gate: `dune test --force` 295/295 (no compiler/source change; zero
regression — script + docs only).

Closes #251. Refs #180 (unblocks ADR-015 S3).
---
 docs/ECOSYSTEM.adoc                    |  7 +++---
 docs/TECH-DEBT.adoc                    |  7 +++---
 tools/provision-component-toolchain.sh | 34 ++++++++++++++++++++++++++
 3 files changed, 42 insertions(+), 6 deletions(-)
 create mode 100755 tools/provision-component-toolchain.sh

diff --git a/docs/ECOSYSTEM.adoc b/docs/ECOSYSTEM.adoc
index 4b0390c5..1cc536a5 100644
--- a/docs/ECOSYSTEM.adoc
+++ b/docs/ECOSYSTEM.adoc
@@ -206,9 +206,10 @@ satellite shell is downstream.
 |INT-03 |WASI preview2 / host I/O beyond stdout |#180 |S1, ADR-015
 ACCEPTED (owner-chosen full WASM Component-Model re-target). Staged
 S1..S6; legacy preview1 stdout path is the default until S6
-(reversible-in-progress). S3+ HARD-GATED on S2 toolchain provisioning
-(`wasm-tools`/`wasm-component-ld`, absent). WIT world of record:
-`wit/affinescript.wit`
+(reversible-in-progress). **S2 toolchain provisioned (#251 closed):
+`tools/provision-component-toolchain.sh` — pinned wasm-tools 1.249.0 /
+wasm-component-ld 0.5.22 / wac-cli 0.10.0. S3 (componentize on-ramp)
+now UNBLOCKED.** 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
diff --git a/docs/TECH-DEBT.adoc b/docs/TECH-DEBT.adoc
index 04398291..13c7cca0 100644
--- a/docs/TECH-DEBT.adoc
+++ b/docs/TECH-DEBT.adoc
@@ -185,9 +185,10 @@ follow-up
 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-03 |WASI preview2 / host I/O |S1→S2 |#180 ADR-015 (full
+Component-Model re-target, S1..S6); **S2 toolchain provisioned —
+#251 closed (`tools/provision-component-toolchain.sh`, pinned
+wasm-tools/wasm-component-ld/wac); S3 componentize on-ramp unblocked**
 |INT-04 |Publish to JSR/npm |S2 |#181 packaging READY (dry-run green,
 manual workflow); JSR publish authorised + dispatched (owner go
 2026-05-19); compiler-binary distribution decided = **ADR-019**
diff --git a/tools/provision-component-toolchain.sh b/tools/provision-component-toolchain.sh
new file mode 100755
index 00000000..44ba1b40
--- /dev/null
+++ b/tools/provision-component-toolchain.sh
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: PMPL-1.0-or-later
+#
+# INT-03 S2 / issue #251 (ADR-019 unblocker for ADR-015 S3+): provision
+# the WASM Component-Model toolchain the WASI-preview2 migration needs.
+#
+# Reproducible by construction: exact pinned versions + `cargo install
+# --locked` (uses each crate's committed Cargo.lock, so the built
+# binary is deterministic for the pinned version). Re-running is
+# idempotent (cargo skips an already-installed matching version).
+#
+# Canonical provisioning is this script for now; a guix.scm / flake.nix
+# devShell entry is a tracked follow-up (the repo has neither yet —
+# introducing one is out of #251's bounded scope). CI and contributors
+# run this to obtain a byte-stable toolchain.
+#
+# Pinned 2026-05-19 (resolved + verified on rustc 1.95.0):
+set -euo pipefail
+
+WASM_TOOLS_VERSION="1.249.0"
+WASM_COMPONENT_LD_VERSION="0.5.22"
+WAC_CLI_VERSION="0.10.0"
+
+echo "Provisioning component-model toolchain (pinned, --locked)…"
+cargo install --locked --version "${WASM_TOOLS_VERSION}"        wasm-tools
+cargo install --locked --version "${WASM_COMPONENT_LD_VERSION}" wasm-component-ld
+cargo install --locked --version "${WAC_CLI_VERSION}"           wac-cli
+
+echo
+echo "Installed:"
+wasm-tools --version
+wasm-component-ld --version
+wac --version
+echo "OK — ADR-015 S3 (componentize on-ramp) is now unblocked."