fix(ci,on-ramp): make CI green on main and give downstream consumers a real on-ramp (#771)

.github/workflows/ci.yml

@@ -85,7 +85,35 @@ jobs:
       - name: Build
         run: opam exec -- dune build
       - name: Run tests
-        run: opam exec -- dune runtest
+        run: |
+          set -o pipefail
+          opam exec -- dune runtest 2>&1 | tee runtest.log
+      # ── TEMPORARY DIAGNOSTIC (removed before merge) ───────────────────────
+      # Republishes the failure + a downstream probe as annotations, so the
+      # result is readable through the API rather than the Actions log UI.
+      - name: "[diag] surface runtest failure and probe downstream"
+        if: always()
+        run: bash tools/ci/diag-probe.sh
+      # ─────────────────────────────────────────────────────────────────────
+      - name: Consumer on-ramp example (issue #771)
+        # The consumer-facing contract this project owes its downstream
+        # readers: a host surface declared with `extern fn`, compiled to
+        # wasm, driven by a host that supplies the imports, errors carried as
+        # stable integer codes. docs/ON-RAMP.adoc is the prose; this is the
+        # executable half, and it is gated so the on-ramp cannot rot the way
+        # blocky-writer's "just tell us how to build" ask did. The example
+        # finds the compiler three ways (in-tree build / PATH / dune exec),
+        # so it exercises the same entry point a consumer has.
+        run: ./examples/consumers/extension-boundary/build.sh
+      - name: WASM harness instantiation-idiom gate
+        if: ${{ !cancelled() }}
+        # tests/**/*.mjs must not mix the two WebAssembly.instantiate
+        # overloads (Module -> Instance vs BufferSource -> { module, instance }).
+        # A mix-up yields `undefined` and, before the codegen WASM runner was
+        # made fail-late, aborted the harness loop at the first bad file and
+        # silently masked every harness after it (33 of them).
+        # See tools/check-wasm-harness-idioms.sh.
+        run: ./tools/check-wasm-harness-idioms.sh
       - name: Run codegen WASM tests
         run: opam exec -- ./tools/run_codegen_wasm_tests.sh
       - name: Run codegen Bun-ESM tests (historical codegen-deno corpus)

.github/workflows/governance-baseline.yml

@@ -35,12 +35,28 @@ on:
     branches: [main, master]
   pull_request:
   workflow_dispatch:
-# Caller-side concurrency only. The local reusable deliberately declares NO
-# concurrency block: a reusable that declares concurrency on the same computed
-# key as its caller is rejected at run-creation (the BP008 class).
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+# NO `concurrency:` block — deliberately, and this is the fix for a 30-for-30
+# `startup_failure` streak (every run this workflow has ever had, from its
+# first push to 2026-10-03).
+#
+# The BP008 class is caller-plus-callee, not callee-only: a reusable-workflow
+# caller that declares `concurrency` alongside a callee that also declares it
+# is rejected at *run-creation* — no job, no `check_run`, and therefore no
+# way for the pinned context `governance / Validate Hypatia baseline` to ever
+# report. An earlier pass removed the block from the local reusable
+# (`governance-baseline-impl.yml`, which still has none) and left the
+# caller's in place, so the collision survived and the streak continued.
+#
+# The evidence for removing the caller's block instead is the sibling
+# workflow that works: `spark-theatre-gate.yml` is the estate's other
+# reusable caller, it carries the same "NO workflow-level concurrency" note
+# for the same reason, and its context reports on every PR. `governance.yml`
+# keeps its concurrency block precisely because it is a *normal* workflow,
+# not a caller.
+#
+# Consequence, recorded rather than hidden: two runs of this bridge on the
+# same ref are no longer auto-cancelled. The bridge is a ~5 s `jq` check, so
+# that is an acceptable price for a context that actually reports.
 permissions:
   contents: read
 jobs:

.github/workflows/zz-probe-a.yml

@@ -0,0 +1,18 @@
+# This workflow is managed by gh actions-lock.
+# SPDX-License-Identifier: MPL-2.0
+#
+# TEMPORARY PROBE (deleted before merge) — hypothesis A:
+# the local reusable call fails at run-creation because the CALLER JOB does
+# not grant permissions explicitly (the only reusable caller in this repo that
+# works, spark-theatre-gate.yml, does grant them at job level). Same shape as
+# governance-baseline.yml, plus job-level permissions.
+name: ZZ Probe A
+on:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  governance:
+    uses: ./.github/workflows/governance-baseline-impl.yml
+    permissions:
+      contents: read

.github/workflows/zz-probe-b.yml

@@ -0,0 +1,23 @@
+# This workflow is managed by gh actions-lock.
+# SPDX-License-Identifier: MPL-2.0
+#
+# TEMPORARY PROBE (deleted before merge) — hypothesis B: no reusable workflow
+# at all, and the pinned context reproduced by naming the job literally.
+# A normal (non-caller) workflow always starts, so this is what the bridge
+# becomes if the reusable mechanism itself is what the platform refuses.
+name: ZZ Probe B
+on:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  governance:
+    name: Validate Hypatia baseline
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7.0.1
+      - name: Validate .hypatia-baseline.json (if present)
+        run: |
+          echo "probe B: plain job, no reusable workflow"

README.adoc

@@ -86,20 +86,34 @@ write(buf, "world")     # error: 'buf' was already used up by close()
 
 == Quick start
 
-// TODO: replace this block with the real toolchain commands.
+Build the compiler from a checkout (the only route that works today — see
+link:docs/ON-RAMP.adoc[docs/ON-RAMP.adoc] for why the release-binary and
+JSR-shim routes do not yet):
+
 [source,console]
 ----
-# install
-$ <install command here>
+$ git clone https://github.com/hyperpolymath/affinescript && cd affinescript
+$ opam install . --deps-only --with-test --yes
+$ dune build
+
+# lex / parse / type-check / evaluate a program
+$ dune exec affinescript -- check examples/hello.affine
 
-# compile a face program to WebAssembly
-$ <compiler invocation here> hello.rattle -o hello.wasm
+# compile it to WebAssembly
+$ dune exec affinescript -- compile examples/hello.affine -o hello.wasm
 
-# run it
-$ <runner invocation here> hello.wasm
+# or to an ES module for a JavaScript host
+$ dune exec affinescript -- compile examples/hello.affine -o hello.bun.js --bun-esm
 ----
 
-A runnable example lives in `examples/` once the toolchain lands.
+If you are *consuming* AffineScript — a project outside this repository that
+wants a compiler, a target, and a host boundary — read
+link:docs/ON-RAMP.adoc[docs/ON-RAMP.adoc] instead of the rest of this file.
+It states what exists and what does not.
+
+A complete, CI-gated consumer lives in
+`examples/consumers/extension-boundary/`; `just on-ramp-example` builds and
+runs it.
 
 == How it works
 

docs/NAVIGATION.adoc

@@ -80,6 +80,7 @@ This guide helps you navigate the AffineScript repository structure.
 
 **Guides:**
 
+* link:ON-RAMP.adoc[Consumer On-Ramp] - **Start here if you are consuming AffineScript from another project** — getting a compiler, targets, declaring a host surface with `extern fn`, carrying errors across the wasm boundary (#771)
 * link:CAPABILITY-MATRIX.adoc[Capability Matrix] - **Live** per-component readiness (authoritative for feature readiness)
 * link:SOUNDNESS.adoc[Soundness Ledger] - **Live** test-anchored soundness-hole status (authoritative for "is it sound?"; the matrix links here). *Start here for soundness questions.*
 * link:PROOF-NEEDS.adoc[Proof-Needs Inventory] - what must be *proven* (mostly unmechanised); distinct from the soundness ledger above