examples/: hello-world + kitchen-sink — runnable, self-checking embedder examples

.github/justfile

@@ -55,6 +55,7 @@ core:
     @just gha::_step test-wasi-shims
     @just gha::_step test-ct-runner
     @just gha::_step test-bundle
+    @just gha::_step examples
     @just gha::_step conformance
     @just gha::_step sched-seeds
     @just gha::_step test-ports

README.md

@@ -38,6 +38,7 @@ Pre-1.0, but densely gated:
 | `crates/translator-shim` | wasmtime-environ + FACT → versioned plan format (wasm32, runs everywhere) |
 | `runtime/` | TS core: plan executor, canonical ABI, 0.3 task scheduler, JSPI bridge, embedder API (`runtime/src/embedder`) |
 | `crates/bindgen` | WIT → TypeScript types for the embedder conventions |
+| `examples/` | **start here to embed**: hello-world + kitchen-sink (WIT + Rust guest + TS host, self-checking), plus the guest fixture corpus |
 | `wasi-shims/` | minimal WASI providers (p2 baseline + p3 clocks), one per semver track |
 | `ct-runner/` | conformance-suite runner for the polymorph-test L1 contract |
 | `harness/` + `tools/browser` | official-suite harness; Deno lane + Chromium/Firefox/WebKit lanes |
@@ -61,6 +62,7 @@ is the command surface (`just --list`; recipe bodies are the exact commands).
 
 | Where | What |
 |---|---|
+| [`examples/`](examples/) | runnable embedder examples: [hello-world](examples/hello-world/) (smallest complete embedding) and [kitchen-sink](examples/kitchen-sink/) (imports incl. suspending, resources both directions, value-shape tour) |
 | [`docs/architecture.md`](docs/architecture.md) | the system design and decisions, with rationale (§-numbered; cited from code comments) |
 | [`docs/milestones.md`](docs/milestones.md) | the verified milestone record (S0 → C3) |
 | [`docs/consumers.md`](docs/consumers.md) | the polymorph adoption track: jco blocker mapping, cutover evidence, in-repo ports |

deno.json

@@ -1,3 +1,9 @@
 {
-  "workspace": ["./runtime", "./harness", "./wasi-shims", "./ct-runner"]
+  "workspace": [
+    "./runtime",
+    "./harness",
+    "./wasi-shims",
+    "./ct-runner",
+    "./examples"
+  ]
 }

examples/.gitignore

@@ -1,4 +1,9 @@
-# Component outputs and cargo build artifacts (rebuild with ./build.sh)
+# Component outputs and cargo build artifacts (rebuild with ./build.sh
+# or the per-example run.sh).
 guests/build/
 guests/target/
 guests/*/target/
+hello-world/build/
+hello-world/guest/target/
+kitchen-sink/build/
+kitchen-sink/guest/target/

examples/README.md

@@ -1,7 +1,26 @@
-# examples/ — Rust guest fixture corpus
+# examples/
+
+Two things live here, for two audiences:
+
+## Embedder examples (start here if you're using deltic)
+
+Complete, self-contained, self-checking WIT + Rust-guest + TS-host pairs.
+Each directory can be copied out of the repo and built as-is; each `run.sh`
+builds the guest component and runs the host under Deno (`just examples`
+runs both, and CI does too — these cannot silently rot).
+
+| example | what it teaches |
+|---|---|
+| [`hello-world/`](hello-world/) | the smallest complete embedding: translate → instantiate → call one export; no imports |
+| [`kitchen-sink/`](kitchen-sink/) | a representative tour: imports (sync / fallible / **suspending**), resources both directions, and the non-obvious value spellings (enum, variant, flags, outermost vs nested option/result, the option-boxing rule) |
+
+The normative reference behind both is
+[`contracts/embedder-api.md`](../contracts/embedder-api.md).
+
+## Rust guest fixture corpus (`guests/`)
 
 Guest components built with **wit-bindgen** (the compatibility target of this
-project, docs/architecture.md §1/§11). The future TS host runs these as its executable
+project, docs/architecture.md §1/§11). The TS host runs these as its executable
 wit-bindgen-compat claim. Each guest is a pure computational reactor — **no
 WASI imports** — so componentization needs no wasip1 adapter.
 

examples/deno.json

@@ -0,0 +1,10 @@
+{
+  "name": "@deltic/examples",
+  "version": "0.0.0",
+  "exports": {},
+  "tasks": {
+    "hello-world": "./hello-world/run.sh",
+    "kitchen-sink": "./kitchen-sink/run.sh",
+    "check": "deno check hello-world/host.ts kitchen-sink/host.ts"
+  }
+}

examples/hello-world/README.md

@@ -0,0 +1,30 @@
+# hello-world — the smallest complete embedding
+
+One exported function, no imports. Three files matter:
+
+| file | role |
+|---|---|
+| [`wit/world.wit`](wit/world.wit) | the contract: `greet: func(name: string) -> string` |
+| [`guest/src/lib.rs`](guest/src/lib.rs) | the Rust guest (wit-bindgen) implementing it |
+| [`host.ts`](host.ts) | the host: translate → instantiate → call |
+
+Run it:
+
+```sh
+just shim          # once, from the repo root: builds the translator
+./run.sh           # builds the guest component, runs the host
+```
+
+What to notice:
+
+- **Exports are Promise-shaped** — `await component.exports.greet(...)`
+  even though this guest is synchronous. One calling convention for sync
+  and async guests (contracts/embedder-api.md §"Functions and async").
+- **Strings just work** — the guest returns a heap-allocated string; the
+  canonical ABI's realloc dance is the runtime's problem, not yours.
+- **The imports record is empty** — this world imports nothing. For the
+  full imports story (interfaces, resources, error model, suspending
+  imports) continue to [`../kitchen-sink`](../kitchen-sink).
+
+The authoritative reference for everything the host sees is
+[`contracts/embedder-api.md`](../../contracts/embedder-api.md).