@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MPL-2.0
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+#
+# Build + run the consumer on-ramp example (issue #771).
+#
+# This is the "smallest thing" the consumer asked for, in executable form:
+#
+#   ./build.sh          compile src/boundary.affine -> dist/boundary.wasm,
+#                       then run the Node harness against it.
+#
+# The compiler is located the three ways a consumer legitimately has it:
+# an in-tree dune build (a checkout of this repo), an `affinescript` on
+# PATH (a release binary), or `dune exec` (a checkout without a prior
+# build). Nothing else is required — no deno.json, no npm manifest, no
+# bundler config.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$HERE/../../.." && pwd)"
+
+SRC="$HERE/src/boundary.affine"
+OUT_DIR="$HERE/dist"
+OUT="$OUT_DIR/boundary.wasm"
+
+if [ -x "$ROOT/_build/default/bin/main.exe" ]; then
+  COMPILE=("$ROOT/_build/default/bin/main.exe" compile)
+elif command -v affinescript >/dev/null 2>&1; then
+  COMPILE=(affinescript compile)
+else
+  COMPILE=(dune exec affinescript -- compile)
+fi
+
+mkdir -p "$OUT_DIR"
+
+echo "Compiling $(basename "$SRC") -> $(basename "$OUT")"
+"${COMPILE[@]}" "$SRC" -o "$OUT"
+
+echo "Running host.mjs"
+node "$HERE/host.mjs"
@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: MPL-2.0
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+//
+// Node ESM harness for examples/consumers/extension-boundary.
+//
+// This file is the other half of the on-ramp: it shows exactly how a host
+// satisfies the `extern fn` surface declared in src/boundary.affine, and
+// what the assertable contract looks like in CI. Node is used because CI
+// already has it; nothing here is Node-specific except `readFile`, so the
+// same object literal works in Deno, Bun, or a browser extension
+// (`WebAssembly.instantiate` with the same `imports`).
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+// The error taxonomy a real consumer needs is stable and enumerated. These
+// are the codes the host returns; the guest only ever sees integers.
+const BW = {
+  OK: 0,
+  BW_PDF_ENCRYPTED: 1042,
+  BW_NO_BLOCKS_FOUND: 1051,
+};
+
+// The host owns the message text. Nothing crosses the boundary as a string
+// — `bw_error_message_*` is a byte-wise accessor over this value.
+const MESSAGES = {
+  [BW.BW_PDF_ENCRYPTED]: "document is encrypted; decrypt before filling",
+  [BW.BW_NO_BLOCKS_FOUND]: "no fillable blocks detected in document",
+};
+
+// `context` is the third leg of the {code, message, context} payload the
+// consumer contract requires; it stays host-side too.
+let lastFailure = null;
+
+function fail(code, context) {
+  lastFailure = { code, message: MESSAGES[code] ?? "", context };
+  return code;
+}
+
+const calls = { detect: 0, fill: 0 };
+
+const imports = {
+  wasi_snapshot_preview1: {
+    // Nothing in this guest touches WASI, but the compiler links the
+    // preview-1 surface when the file mentions effects; a stub keeps the
+    // instantiation total rather than depending on what codegen emitted.
+    fd_write: () => 0,
+  },
+  env: {
+    bw_detect_blocks: (pdfLen) => {
+      calls.detect += 1;
+      assert.ok(Number.isInteger(pdfLen) && pdfLen > 0, "host got the length");
+      return BW.OK;
+    },
+    bw_fill_blocks: (pdfLen, fieldCount) => {
+      calls.fill += 1;
+      assert.ok(Number.isInteger(pdfLen) && pdfLen > 0, "host got the length");
+      assert.ok(fieldCount > 0, "host got the field count");
+      // Second document is encrypted — the failure path, deliberately.
+      return fail(BW.BW_PDF_ENCRYPTED, { pdfLen, fieldCount });
+    },
+    bw_error_code: () => lastFailure?.code ?? BW.OK,
+    bw_error_message_len: () => lastFailure?.message.length ?? 0,
+    bw_error_message_byte: (offset) =>
+      lastFailure?.message.charCodeAt(offset) ?? 0,
+  },
+};
+
+const wasmPath = join(here, "dist", "boundary.wasm");
+const bytes = await readFile(wasmPath);
+const { instance } = await WebAssembly.instantiate(bytes, imports);
+const guest = instance.exports;
+
+// ── The contract, asserted ───────────────────────────────────────────────
+
+// 1. Success path: the guest normalises "host said 0" to 0.
+assert.equal(guest.detect(4096), 0, "detect returns 0 on success");
+assert.equal(guest.is_ok(0), 1, "is_ok(0) is true");
+assert.equal(guest.message_len(0), 0, "no message for a success status");
+assert.equal(calls.detect, 1, "host detected once");
+
+// 2. Failure path: the guest propagates the stable code, not a string.
+assert.equal(
+  guest.fill(4096, 3),
+  BW.BW_PDF_ENCRYPTED,
+  "fill propagates the host's BW_* code",
+);
+assert.equal(calls.fill, 1, "host filled once");
+
+// 3. The message is host-owned and byte-addressable, exactly as declared.
+const len = guest.message_len(BW.BW_PDF_ENCRYPTED);
+assert.equal(len, MESSAGES[BW.BW_PDF_ENCRYPTED].length, "message length crosses");
+const rebuilt = Array.from({ length: len }, (_, i) =>
+  String.fromCharCode(guest.message_byte(BW.BW_PDF_ENCRYPTED, i)),
+).join("");
+assert.equal(rebuilt, MESSAGES[BW.BW_PDF_ENCRYPTED], "message round-trips");
+assert.equal(guest.message_len(0), 0, "success still has no message");
+
+// 4. The consumer-facing payload shape: {code, message, context} — never a
+//    bare string, which is the taxonomy requirement this example exists for.
+assert.deepEqual(lastFailure, {
+  code: BW.BW_PDF_ENCRYPTED,
+  message: MESSAGES[BW.BW_PDF_ENCRYPTED],
+  context: { pdfLen: 4096, fieldCount: 3 },
+});
+
+// 5. The guest's public surface is what the consumer advertised — a
+//    two-function boundary plus the error accessors.
+for (const name of [
+  "detect", "fill", "is_ok", "message_len", "message_byte",
+]) {
+  assert.equal(typeof guest[name], "function", `${name} is exported`);
+}
+
+console.log("examples/consumers/extension-boundary: OK");
@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: MPL-2.0
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+//
+// Consumer on-ramp example (issue #771) — the "extension boundary" shape.
+//
+// This module is what a downstream consumer writes. It is deliberately
+// shaped after the first real consumer request the project received: a
+// browser extension with a WASM core behind a two-function boundary
+// (`detect` / `fill`), whose error taxonomy has to cross that boundary as
+// stable integer codes plus a message the host owns.
+//
+// Two things are being demonstrated:
+//
+//   1. A consumer owns its own host surface. The `extern fn` declarations
+//      below are the entire binding story: the WASM backend emits one
+//      `(import "env" "<name>")` per declaration, and the host supplies
+//      them in the import object. No compiler change is needed to add a
+//      host function.
+//
+//   2. Errors do not cross as strings. The guest returns a status code
+//      (0 = ok, non-zero = a stable `BW_*` code) and asks the host for the
+//      message only when a human needs to read it.
+//
+// Compile:
+//   affinescript compile src/boundary.affine -o dist/boundary.wasm
+// Run the harness:
+//   node host.mjs
+
+module boundary;
+
+// ── The host surface this consumer owns ──────────────────────────────────
+// Implemented in the host's `env` import object (see host.mjs). Params and
+// results are i32 across the WASM boundary.
+
+/// Scan a document for fillable blocks. PDF bytes stay host-side; the guest
+/// passes only the length it was told about. Returns 0 or a `BW_*` code.
+pub extern fn bw_detect_blocks(pdf_len: Int) -> Int;
+
+/// Write field values into the blocks found by `bw_detect_blocks`.
+/// `field_count` is the number of entries the host handed over. Returns 0
+/// or a `BW_*` code.
+pub extern fn bw_fill_blocks(pdf_len: Int, field_count: Int) -> Int;
+
+/// The `BW_*` code for the most recent failure. Always safe to call.
+pub extern fn bw_error_code() -> Int;
+
+/// Byte length of the host-owned message for the most recent failure.
+pub extern fn bw_error_message_len() -> Int;
+
+/// Byte `offset` of the host-owned message for the most recent failure.
+pub extern fn bw_error_message_byte(offset: Int) -> Int;
+
+// ── Guest-side vocabulary ────────────────────────────────────────────────
+
+/// Status values are the `BW_*` taxonomy, narrowed to the two the guest
+/// reasons about: 0 is success, anything else is a failure whose detail
+/// lives host-side.
+pub fn is_ok(status: Int) -> Bool {
+  status == 0
+}
+
+/// Detect blocks, normalising the host's status to the documented
+/// "0 = ok, non-zero = BW_* code" contract.
+pub fn detect(pdf_len: Int) -> Int {
+  let status = bw_detect_blocks(pdf_len);
+  if is_ok(status) { 0 } else { bw_error_code() }
+}
+
+/// Fill blocks. Same normalisation as `detect`.
+pub fn fill(pdf_len: Int, field_count: Int) -> Int {
+  let status = bw_fill_blocks(pdf_len, field_count);
+  if is_ok(status) { 0 } else { bw_error_code() }
+}
+
+/// Length of the human-readable message for `status`, or 0 when `status`
+/// is success. The guest never materialises the message as a String: the
+/// host owns it, and the guest asks for it only when someone will read it.
+pub fn message_len(status: Int) -> Int {
+  if is_ok(status) { 0 } else { bw_error_message_len() }
+}
+
+/// Byte of the human-readable message for `status`, or 0 when `status` is
+/// success. Mirrors `message_len`.
+pub fn message_byte(status: Int, offset: Int) -> Int {
+  if is_ok(status) { 0 } else { bw_error_message_byte(offset) }
+}