diff --git a/design/TESTPROVIDER_ASSESSMENT.md b/design/TESTPROVIDER_ASSESSMENT.md
new file mode 100644
index 0000000..fe9da39
--- /dev/null
+++ b/design/TESTPROVIDER_ASSESSMENT.md
@@ -0,0 +1,187 @@
+# Test Provider — suitability as a general library, and what's missing
+
+**Status:** assessment / proposal (2026-06). Evaluates the `test/proto/`
+prototypes (see [`../test/proto/PROVIDER.md`](../test/proto/PROVIDER.md),
+[`RUNNING.md`](../test/proto/RUNNING.md),
+[`AGENTS.md`](../test/proto/AGENTS.md)) against the bar of being a *general
+library for test-spec provision* — something a port's test suite, or a coding
+agent, depends on to consume the shared corpus. Nothing here is implemented.
+
+> **Verdict.** As a prototype proving the shape: suitable — the model and the
+> 22-language parity are right. As a drop-in general library today: not yet.
+> Gaps §3.1–§3.4 are correctness/usability blockers, not polish. The cleanest
+> path is to push the *invoke-mapping* and *null-mode* into the test-spec model
+> (the aontu schema strand, [`TESTSPEC_MODEL.md`](./TESTSPEC_MODEL.md)), which
+> turns the provider from "data + an external cheat-sheet" into a genuinely
+> self-contained library; only then is packaging worth the spend.
+
+
+## 1. What the prototype is
+
+A data-access library, ported to all 22 languages and verified to emit the same
+normalized view of `build/test/test.json` — **1325 entries** (value 1181,
+absent 84, error 59, match 1). It loads the corpus, classifies
+`struct.<fn>.<group>.set[]` into normalized `Entry` records (tagged `Input`,
+tagged `Expect`, provenance), and ships pure comparison helpers
+(`equal`/`equalStrict`/`structMatch`/`errorMatches`/`matchval`). It is **not** a
+runner: it never calls the function under test and never asserts.
+
+
+## 2. What is already library-grade
+
+* **Uniform model across 22 languages, proven identical.** Cross-language
+  parity is the expensive part and it is done and run-verified.
+* **Dependency-free**, with an order-preserving JSON reader (stdlib or
+  hand-rolled) in every port.
+* **The fiddly logic is centralized.** `structMatch` (regex / `__UNDEF__` /
+  `__EXISTS__` / partial deep match) and the `equal` vs `equalStrict` null
+  semantics are written once per port instead of re-derived in each test file.
+* **Good authoring ergonomics.** Tagged input/expect + provenance
+  (`function/group/index/id`) make per-case tests and failure messages clean.
+
+
+## 3. Gaps that block general use (prioritized)
+
+### 3.1 The invoke-mapping lives *outside* the library  ⟵ #1
+The provider hands you `entry.input.in = {store, path}` but not that it maps to
+`getpath(store, path)`. That knowledge is prose in `AGENTS.md` §3, not data.
+Every consumer must hand-maintain that table — exactly the drift this repo
+exists to prevent. **Highest-value gap.** (Proposal: §4.1.)
+
+### 3.2 The `null:false` mode is not in the corpus
+Whether a case is compared with `equal` or `equalStrict` is set by the test
+author per `runset` call — i.e. **per (function, group)** (e.g. `validate.basic`
+is strict, `validate.child` is not; `transform.format` is strict, sibling
+groups are not; all of `minor.clone`, all `sentinels`, `walk.depth`, …). The
+provider cannot currently tell a caller the right comparison mode. A silent
+correctness hazard. (Proposal: §4.1.)
+
+### 3.3 The `args`/`ctx` input paths are effectively untested
+All 1325 iterated entries are `kind:in`. The only `args`/`ctx`/`DEF.client`
+data lives under `primary.check`, which `functions()` deliberately skips. So
+those provider branches are written but never exercised, and the entire
+client-integration spec is unreachable through the provider. (Proposal: §4.2.)
+
+### 3.4 No clone-on-read
+`raw` and `input.in` are returned by reference. The real runner *clones*
+`entry.in` before each call precisely so a subject can't mutate shared
+corpus/fixtures; a test that mutates input here would corrupt later cases.
+(Proposal: §4.3.)
+
+### 3.5 The helpers are a reimplementation, not the port's own semantics
+The runner matches using each port's *own* `struct.walk`/`getpath`/`stringify`;
+the provider ships generic equivalents. Self-contained, but they can diverge
+from a port's real semantics on edge cases (array indexing, special keys,
+stringify formatting). Fine as a data utility, riskier as the assertion
+authority — see the ownership decision in §4.6.
+
+### 3.6 Corpus discovery is hardcoded
+The default path assumes the in-repo `build/test/test.json` layout. A library
+shipped inside a port's package will not know where the consumer's corpus is
+(the runner already hints at a `.sdk/test/test.json` alternative for sdkgen
+projects). Needs explicit/configurable resolution.
+
+### 3.7 Thin API, and the provider itself is untested
+No `byId()`, no filtering (by `doc`, by `client`), no access to the `primary`
+namespace or to fixtures except via `raw()`. The provider's own logic is only
+*smoke*-tested (counts) — the helpers have no conformance suite, and there is no
+cross-port parity check (the analogue of `tools/check_parity.py`) keeping the 22
+APIs and behaviours in sync.
+
+### 3.8 Packaging
+Loose single files under `test/proto/`, not consumable packages, with per-port
+run quirks (swift `main.swift`, clojure ns/path depth, scala classpath) and
+cosmetic inconsistencies (sorted vs insertion-order kind printing in smokes).
+
+
+## 4. What else is needed
+
+### 4.1 Encode invoke-mapping + null-mode in the model  (resolves §3.1, §3.2)
+This is where the provider converges with the aontu schema work
+([`TESTSPEC_MODEL.md`](./TESTSPEC_MODEL.md)). Add **emitted** descriptors the
+provider can read. Sketch:
+
+```jsonic
+# per function: how an entry's input maps onto the call
+struct: getpath: api: { args: ['in.store', 'in.path'] }
+struct: merge:   api: { args: ['in'] }            # in is the whole arg
+struct: select:  api: { args: ['in.obj', 'in.query'] }
+
+# per group: comparison mode (default true = equal; false = equalStrict)
+struct: validate: basic: nullmode: false
+struct: transform: format: nullmode: false
+```
+
+* `args` is a list of **dotted path-expressions** resolved against the entry
+  (`in.store`, `in`, …). The provider can then build the argument vector itself,
+  and `AGENTS.md`'s mapping table disappears.
+* **Honest limit:** not every call is pure-data-dispatchable. `filter` takes a
+  predicate selected by `in.check`, `walk` takes a callback, `transform.modify`
+  takes a modifier, `getpath.handler`/`inject`/`validate.special` take an
+  injection/current. These need a small set of **named resolvers** the consumer
+  registers once (e.g. `resolvers = { check: …, walkcb: … }`) and the model
+  references (`args: ['in.val', {resolver: 'check', key: 'in.check'}]`). So the
+  end state is *data-driven dispatch for the ~80% case + a handful of named
+  hooks*, not magic.
+* `nullmode` is **per-group** (§3.2). Default emitted from the
+  `struct.&` template so only the exceptions are written.
+
+These fields are additive — existing port runners ignore unknown keys, so
+`test.json` consumers are unaffected (verify with the zero-diff guard from
+`TESTSPEC_MODEL.md` §5, treating the new keys as intended additions).
+
+### 4.2 Model `primary` / `DEF` / `client` / fixtures as first-class  (§3.3)
+Expose `primary.check` through the provider (a `clients()` / `entries('check')`
+path), surface a group's `DEF` and fixtures via typed accessors rather than
+`raw()`, and add `args`/`ctx` corpus coverage so those branches are real. Ties
+to the `fixtures`/`DEF` slots proposed in `TESTSPEC_MODEL.md` §4.4.
+
+### 4.3 Clone-on-read or a documented immutability contract  (§3.4)
+Either deep-clone `input`/`raw` on access (matches the runner), or document that
+returned values are shared-immutable and provide an explicit `clone(entry)`.
+Prefer clone-on-read for `input` (the thing tests touch most).
+
+### 4.4 A provider-level conformance corpus + cross-port parity check  (§3.7)
+A small fixed set of `(helper, args, expected)` cases — especially for
+`structMatch`/`matchval`/`equalStrict` edge cases — that every port runs, plus a
+`tools/check_provider_parity.py` that asserts all 22 expose the same API and
+pass that set. Without it, 22 hand-written ports *will* drift.
+
+### 4.5 Configurable corpus discovery  (§3.6)
+`load(path)` explicit, plus a documented search order (env var → walk up for
+`build/test/test.json` or `.sdk/test/test.json` → error). Fixes the
+clojure/depth fragility noted in `RUNNING.md` along the way.
+
+### 4.6 Decide who owns the assertion logic  (§3.5)
+Pick one and commit:
+* **(a) Provider = data only.** Drop the helpers; the port's own `struct` utils
+  do matching. Maximally faithful, but every test reimplements comparison.
+* **(b) Provider = the authority.** Keep the helpers but give them the
+  conformance suite from §4.4 so they are provably correct, and document that
+  they intentionally define corpus-match semantics independent of any port.
+
+Recommendation: **(b)** — centralizing comparison is most of the value; just
+make it earn the authority with tests.
+
+### 4.7 Packaging  (§3.8)
+Per-language module/package layout, consistent smoke output, and a decision on
+*home*: stay in `test/proto/` as reference, or vendor each port's provider into
+that port's package so its test suite imports it directly.
+
+
+## 5. Suggested order
+
+1. **§4.1** (invoke-mapping + null-mode in the model) — unblocks the rest and is
+   the throughline with the schema work. Do it in the corpus model first, then
+   teach the canonical TS provider to read it, then propagate.
+2. **§4.3** clone-on-read and **§4.5** corpus discovery — small, pure
+   correctness/robustness wins.
+3. **§4.4** conformance corpus + parity check — lock the 22 together before
+   adding surface area.
+4. **§4.2** primary/DEF/fixtures + args/ctx coverage.
+5. **§4.6 / §4.7** ownership decision and packaging — last, once the contract is
+   stable.
+
+Until §4.1–§4.4 land, treat the prototypes as a **proven core to build on**, not
+a finished library: excellent for an agent writing per-case tests *with* the
+`AGENTS.md` mapping table at hand, not yet a self-contained dependency.
diff --git a/test/proto/.gitignore b/test/proto/.gitignore
new file mode 100644
index 0000000..7f6ce21
--- /dev/null
+++ b/test/proto/.gitignore
@@ -0,0 +1,18 @@
+# Build artifacts from running the prototype smokes — never commit these.
+# Rust
+rust/target/
+# Java / JVM
+*.class
+*.jar
+# C# / .NET
+csharp/bin/
+csharp/obj/
+# OCaml
+*.cmi
+*.cmo
+*.cmt
+*.cmx
+*.o
+# Native binaries
+*.out
+smoke
diff --git a/test/proto/AGENTS.md b/test/proto/AGENTS.md
new file mode 100644
index 0000000..1c2cadf
--- /dev/null
+++ b/test/proto/AGENTS.md
@@ -0,0 +1,149 @@
+# test/proto — agent guidance
+
+You are writing **actual tests** for a `struct` port using the **test provider**
+library in this directory. The provider gives you normalized cases from the
+shared corpus (`build/test/test.json`); you supply the part it deliberately does
+not: *how a case's input maps onto the function call, and how to assert.*
+
+Read [`PROVIDER.md`](./PROVIDER.md) first for the data model. This file is the
+how-to.
+
+## 0. What the provider does and does not do
+
+- **Does:** load `test.json`, enumerate functions/groups, and hand you a flat
+  list of normalized `Entry` records — each with a tagged `input`, a tagged
+  `expect`, and provenance (`function`/`group`/`index`/`id`). Plus pure
+  comparison helpers (`equal`, `equalStrict`, `structMatch`, `errorMatches`,
+  `matchval`).
+- **Does NOT:** call the function under test, assert, or know the function's
+  parameter order. That is your job — it is function-specific (§3).
+
+## 1. The recipe
+
+For each function you are testing:
+
+1. `provider.entries("<fn>")` (optionally per group).
+2. For each entry, **map `entry.input` onto the call** using §3.
+3. Run the call (inside try/catch when an error may be expected).
+4. **Assert against `entry.expect`** by its `kind`:
+
+```
+switch (entry.expect.kind) {
+  VALUE  : assert equal(entry.expect.value, result)          // or equalStrict — §4
+  ERROR  : the call must throw; assert errorMatches(entry.expect.error, message)
+  MATCH  : assert structMatch(entry.expect.match, resultContext).ok
+  ABSENT : assert the result is nullish (null/undefined/None/nil)
+}
+if (entry.expect.match != null && kind != MATCH) also assert structMatch(...)  // co-existing match
+```
+
+For `MATCH`, the runner matches against a *context object*
+`{ in, args, out: result, ctx }`, not the bare result — build the same shape
+before calling `structMatch` (see the `merge` cases, whose match paths start
+`args.0…`).
+
+## 2. Entry quick-reference
+
+```
+entry.function / .group / .index / .id / .doc / .client   # provenance
+entry.input  = { kind: IN|ARGS|CTX, in?, args?, ctx? }
+entry.expect = { kind: VALUE|ERROR|MATCH|ABSENT, value?, error?, match? }
+entry.raw                                                   # original map, escape hatch
+```
+
+`entry.input.in` is usually a small map (`{path, store}`, `{data, spec}`, …) you
+destructure. When `kind` is `ARGS`, spread `entry.input.args`. When `CTX`, the
+function takes the context map (these are the `primary.check` client cases).
+
+## 3. Per-function input → call mapping
+
+Derived from the canonical TS runner. `vin = entry.input.in`. Names are the
+canonical function names (case per your language).
+
+| Function (group)        | Call to make |
+|-------------------------|--------------|
+| `getpath` basic         | `getpath(vin.store, vin.path)` |
+| `getpath` relative/handler | `getpath(vin.store, vin.path, vin.current)` (handler) |
+| `getpath` special       | `getpath(vin.store, vin.path, vin.inj)` |
+| `merge` (most groups)   | `merge(vin)` — `vin` is the list of objects |
+| `merge` depth           | `merge(vin.val, vin.depth)` |
+| `transform` (most)      | `transform(vin.data, vin.spec)` |
+| `transform` modify      | `transform(vin.data, vin.spec, <modifier>)` |
+| `validate` (most)       | `validate(vin.data, vin.spec)` |
+| `validate` special      | `validate(vin.data, vin.spec, vin.inj)` |
+| `inject` deep           | `inject(vin.val, vin.store)` |
+| `select` (all)          | `select(vin.obj, vin.query)` |
+| `walk` basic/copy       | `walk(vin, <callback>)` |
+| `minor.isnode/ismap/islist/iskey/isempty/isfunc/clone/keysof/items/escre/escurl/typename/typify/size` | pass `vin` (or the whole `in`) directly: `fn(in)` |
+| `minor.filter`          | `filter(vin.val, <check from vin.check>)` |
+| `minor.flatten`         | `flatten(vin.val, vin.depth)` |
+| `minor.getprop`         | `getprop(vin.val, vin.key, vin.alt?)` |
+| `minor.getelem`         | `getelem(vin.val, vin.key, vin.alt?)` |
+| `minor.setprop`         | `setprop(vin.parent, vin.key, vin.val)` |
+| `minor.delprop`         | `delprop(vin.parent, vin.key)` |
+| `minor.haskey`          | `haskey(vin.val, vin.key)` |
+| `minor.join`            | `join(vin.val, vin.sep?)` |
+| `minor.slice`           | `slice(vin.val, vin.start, vin.end?)` |
+| `minor.pad`             | `pad(vin.val, …)` |
+| `minor.setpath`         | `setpath(vin.store, vin.path, vin.val)` |
+
+When unsure, open the canonical `typescript/test/utility/StructUtility.test.ts`
+— each `runset(spec.<fn>.<group>, …)` line shows the exact lambda. The corpus is
+the contract; that file is the reference mapping.
+
+## 4. The `null:false` functions — use `equalStrict`
+
+Most functions treat absent ≡ null (use `equal`). These run with the runner's
+`{ null: false }` flag, where an absent/undefined result is **distinct** from
+JSON null — assert them with `equalStrict`:
+
+```
+iskey, strkey, isempty, clone, jsonify, getelem, getprop, haskey, join,
+typify, size, slice, pad, setpath,
+walk.depth, transform.format, validate.basic, validate.invalid,
+and every group under `sentinels`.
+```
+
+(This flag is a property of the function's contract, not the corpus, so it is
+not encoded in `Entry`. If a port disagrees, the corpus + canonical TS win.)
+
+## 5. Worked example (TypeScript, `getpath`)
+
+```ts
+import { TestProvider, equal, errorMatches, structMatch } from './provider'
+import { getpath } from '../../../typescript/dist/StructUtility' // your port's import
+
+const provider = TestProvider.load()
+
+for (const e of provider.entries('getpath')) {
+  const label = e.id ?? `${e.function}/${e.group}#${e.index}`
+  const vin = e.input.in
+  if (e.expect.kind === 'error') {
+    let threw = false
+    try { getpath(vin.store, vin.path) } catch (err: any) {
+      threw = true
+      assert(errorMatches(e.expect.error!, err.message), label)
+    }
+    assert(threw, `${label}: expected an error`)
+  } else if (e.expect.kind === 'value') {
+    assert(equal(e.expect.value, getpath(vin.store, vin.path)), label)
+  } else if (e.expect.kind === 'absent') {
+    assert(equal(null, getpath(vin.store, vin.path)), label)
+  } else if (e.expect.kind === 'match') {
+    const res = getpath(vin.store, vin.path)
+    assert(structMatch(e.expect.match, { in: e.raw.in, out: res }).ok, label)
+  }
+}
+```
+
+Use your language's own test framework for `assert` and iteration — the provider
+is framework-agnostic on purpose.
+
+## 6. Rules
+
+- **Never edit the corpus** to make a test pass (repo-wide rule; see top-level
+  `AGENTS.md`). If a port disagrees with a case, the port is wrong.
+- **Keep the provider a pure data utility.** Comparison helpers must stay
+  side-effect-free; execution and assertion belong in the test you write.
+- **Provenance in failures.** Always include `entry.id` (or
+  `function/group#index`) in assertion messages so a failure points at one case.
diff --git a/test/proto/PROVIDER.md b/test/proto/PROVIDER.md
new file mode 100644
index 0000000..c894ba9
--- /dev/null
+++ b/test/proto/PROVIDER.md
@@ -0,0 +1,167 @@
+# Test Provider — prototype
+
+A small **data-provider** library, ported to each language, that reads the
+shared corpus (`build/test/test.json`) and hands a language's test code clean,
+normalized test cases. It is **not** a test runner: it never calls the function
+under test and never asserts. It answers one question — *"what are the cases,
+and for each, what goes in and what is expected out?"* — and offers a few pure
+helpers for comparing an expectation to a result.
+
+> Status: prototype, ported to all 22 languages (see the matrix below).
+> Canonical behaviour is the TypeScript version (`ts/provider.ts`); the others
+> are ports of it, same as the rest of this repo.
+>
+> **Dependency-free.** Every port is stdlib-only. Where the standard library has
+> no JSON parser (java, c, cpp, rust, lua, kotlin, scala, clojure, elixir,
+> haskell, ocaml) — or has one that reorders object keys (swift) — the port
+> hand-rolls a minimal, order-preserving JSON parser (`functions()`/`groups()`
+> must return corpus order). Ports with an order-preserving stdlib parser use it
+> directly (python, go, js, php, ruby, perl, dart, csharp, zig).
+>
+> **Verification.** **All 22 ports were compiled/run and reproduce the canonical
+> numbers exactly — 1325 entries (value 1181, absent 84, error 59, match 1).**
+> Each port ships a `smoke` file that prints those numbers; the run recipe per
+> language is in `RUNNING.md`. (This is a prototype and is intentionally **not**
+> wired into CI — verify by running a port's `smoke` directly.)
+
+See [`AGENTS.md`](./AGENTS.md) for how a coding agent should *use* this to write
+real tests.
+
+
+## 1. The corpus shape it reads
+
+```
+test.json
+└── struct
+    └── <function>            e.g. getpath, merge, validate, minor.isnode…
+        ├── name              the function name (string)        — skip
+        ├── set               vestigial empty list at fn level  — skip
+        └── <group>           e.g. basic, edge, operators…
+            └── set[]         the test ENTRIES (the leaf units)
+└── primary
+    └── check                 client-integration spec (DEF + groups)
+```
+
+A **group** is any child of a function whose value is a map containing a `set`
+list. `name` (a string) and the function-level empty `set` are not groups.
+
+
+## 2. The normalized `Entry`
+
+Every raw entry map is normalized to a stable record with provenance, one
+**tagged input**, and one **tagged expectation**:
+
+```
+Entry {
+  function : string          # "getpath"
+  group    : string          # "basic"
+  index    : int             # position within the group's set[]
+  id       : string | null   # explicit "<fn>/<group>#<label>" if present
+  doc      : bool            # marked as a documentation example?
+  client   : string | null   # named client from the group's DEF.client
+
+  input    : Input           # tagged — see §3
+  expect   : Expect          # tagged — see §4
+
+  raw      : map             # the original entry, untouched (escape hatch)
+}
+```
+
+## 3. `Input` — tagged, mirrors the runner's precedence (`ctx` → `args` → `in`)
+
+```
+Input {
+  kind : IN | ARGS | CTX
+  in   : <value>     # kind==IN   — the single argument (absent ⇒ native null)
+  args : <list>      # kind==ARGS — explicit positional argument vector
+  ctx  : <map>       # kind==CTX  — context-map invocation
+}
+```
+
+Resolution (exactly the order `resolveArgs` uses):
+1. raw has `ctx` → `CTX`
+2. else raw has `args` → `ARGS`
+3. else → `IN`, with `in = raw.in` (key absent ⇒ native null/None/nil)
+
+The provider does **not** decide how `in`/`args`/`ctx` map onto the function's
+parameters — that is function-specific knowledge the test author supplies
+(`AGENTS.md` §3 lists the shapes).
+
+## 4. `Expect` — tagged value | error | match | absent
+
+```
+Expect {
+  kind  : VALUE | ERROR | MATCH | ABSENT
+  value : <any>          # kind==VALUE — expected result (may be literal null)
+  error : ErrorCheck     # kind==ERROR
+  match : <map>          # kind==MATCH (also populated if a match block co-exists)
+}
+
+ErrorCheck { any: bool, text: string|null, regex: bool }
+```
+
+Resolution (mirrors `checkResult`/`handleError` precedence):
+1. raw has `err` → `ERROR`; `error = parseErr(raw.err)`
+   - `err === true` → `{any:true}`
+   - `"/…/"` → `{any:false, text:<inner>, regex:true}`
+   - other string → `{any:false, text:<string>, regex:false}`
+2. else raw has `out` (key present, even if null) → `VALUE`, `value = raw.out`
+3. else raw has `match` → `MATCH`
+4. else → `ABSENT`
+
+`ABSENT` and `VALUE(null)` both assert a nullish result — the runner defaults an
+absent `out` to "expect null/undefined". They are kept distinct for fidelity.
+If a `match` block is present alongside an `err`/`out`, `expect.match` is also
+set so the test can apply both.
+
+
+## 5. Pure comparison helpers
+
+Side-effect-free; the test calls them to assert. They reproduce the runner's
+comparison logic so each port doesn't re-derive it (and re-introduce its bugs).
+
+```
+matchval(check, base)          -> bool   # scalar primitive (see below)
+equal(expected, actual)        -> bool   # deep equality, null/undef collapsed (runner default null:true)
+equalStrict(expected, actual)  -> bool   # deep equality, undefined ≠ null (runner null:false functions)
+structMatch(check, base)       -> Result # partial structural match; {ok, path?, expected?, actual?}
+errorMatches(check, message)   -> bool   # ErrorCheck vs a thrown message
+```
+
+`equal` vs `equalStrict` mirrors the runner's per-call `null` flag: most
+functions run with `null:true` (absent ≡ null ≡ `__NULL__`, use `equal`); a set
+of functions run with `null:false` (absent is distinct from null, use
+`equalStrict`). The flag is **not** in the corpus — it is the test author's
+choice; `AGENTS.md` §4 lists the `null:false` functions.
+
+* **`matchval(check, base)`** — `check === base`; else if `check` is a string:
+  `"/re/"` ⇒ `RegExp(re).test(stringify(base))`, otherwise
+  `stringify(base).toLowerCase()` *contains* `check.toLowerCase()`; else if
+  `check` is a function ⇒ `true`.
+* **`equal`** — recursive deep-equal after normalizing `__NULL__`→null and
+  absent→null on both sides (mirrors the runner's `flags.null` round-trip).
+* **`structMatch`** — walk the `check` tree; at each leaf compare
+  `getpath(base, path)`: equal ⇒ ok; `__UNDEF__` ⇒ require absent; `__EXISTS__`
+  ⇒ require present; else fall back to `matchval`. First failure returns its
+  path + the two values.
+* **`errorMatches`** — `any` ⇒ true; `regex` ⇒ `RegExp(text).test(message)`;
+  else case-insensitive substring.
+
+`stringify(x)` = `x` if it is already a string, else compact JSON. (The
+canonical runner uses struct's own `stringify`; for the provider this
+approximation is sufficient and documented.)
+
+
+## 6. API surface (per port, idiomatic naming)
+
+```
+TestProvider.load(testfile)    -> provider     # parse test.json
+provider.functions()           -> [string]     # ["minor","getpath",…]
+provider.groups(fn)            -> [string]      # ["basic","relative",…]
+provider.entries(fn)           -> [Entry]       # all entries across fn's groups
+provider.entries(fn, group)    -> [Entry]       # one group's entries
+provider.raw()                 -> map           # the parsed test.json (escape hatch)
+```
+
+Default `testfile` resolves to `build/test/test.json` relative to the repo root;
+tests may pass an explicit path.
diff --git a/test/proto/RUNNING.md b/test/proto/RUNNING.md
new file mode 100644
index 0000000..f8aa127
--- /dev/null
+++ b/test/proto/RUNNING.md
@@ -0,0 +1,78 @@
+# Running the prototype smokes
+
+Every port ships a `smoke` that prints the canonical summary and must show:
+
+```
+functions: minor, getpath, inject, merge, transform, walk, validate, select, sentinels
+total entries: 1325
+expect kinds: value=1181, absent=84, match=1, error=59   (some ports print sorted: absent,error,match,value)
+input kinds: in=1325
+getpath/basic[0]: id=getpath/basic#deep, doc=true, input.kind=in, expect.kind=value, expect.value=42
+```
+
+All 22 were verified with the commands below (run from the repo root unless noted).
+This is a **prototype** — these are run by hand, not in CI.
+
+## Corpus-path convention
+
+Each provider defaults to `build/test/test.json`. Two resolution styles are in use:
+
+* **source-relative** (resolves from the provider file, run from anywhere):
+  ts, javascript, python, php, ruby, perl, go, rust, dart, elixir, lua, swift.
+* **cwd-relative** (run the binary from the repo root): c, cpp, java, kotlin,
+  scala, csharp, zig, ocaml, clojure.
+
+## Per-language commands
+
+| Port | Command |
+|------|---------|
+| typescript | `node --experimental-strip-types test/proto/ts/smoke.ts` |
+| javascript | `node test/proto/javascript/smoke.js` |
+| python | `python3 test/proto/python/smoke.py` |
+| ruby | `ruby test/proto/ruby/smoke.rb` |
+| php | `php test/proto/php/smoke.php` |
+| perl | `perl -I test/proto/perl test/proto/perl/smoke.pl` |
+| lua | `lua5.4 test/proto/lua/smoke.lua` |
+| elixir | `elixir test/proto/elixir/smoke.exs` |
+| go | `cd test/proto/go && go run ./cmd/smoke` |
+| rust | `cd test/proto/rust && cargo run --example smoke` |
+| c | `gcc -std=c11 -O2 test/proto/c/smoke.c -o /tmp/c_smoke -lm && /tmp/c_smoke` |
+| cpp | `g++ -std=c++17 -O2 test/proto/cpp/smoke.cpp -o /tmp/cpp_smoke && /tmp/cpp_smoke` |
+| java | `cd test/proto/java && javac *.java && cd - && java -cp test/proto/java Smoke` |
+| csharp | `cd test/proto/csharp && dotnet run` |
+| zig | `cd test/proto/zig && zig run smoke.zig` |
+| dart | `dart run test/proto/dart/smoke.dart` |
+| haskell | `cd test/proto/haskell && runghc Smoke.hs` |
+| ocaml | `cd test/proto/ocaml && ocamlc -o /tmp/ocaml_smoke provider.ml smoke.ml && cd - && /tmp/ocaml_smoke` |
+| kotlin | `cd test/proto/kotlin && kotlinc Provider.kt Smoke.kt -include-runtime -d /tmp/kt.jar && cd - && java -jar /tmp/kt.jar` |
+| scala | `cd test/proto/scala && scalac -d /tmp/scala_out Provider.scala Smoke.scala && cd - && java -cp "/tmp/scala_out:$SCALA3_LIB/*" Smoke` |
+| swift | `cd test/proto/swift && swiftc Provider.swift main.swift -o /tmp/swift_smoke && /tmp/swift_smoke` |
+| clojure | see note below |
+
+### Toolchain versions used to verify
+
+node 22 · python 3.11 · go 1.24 · rustc 1.94 · php 8.3 · ruby 3 · perl 5 ·
+gcc/g++ 13 · openjdk 21 · dotnet 8 · zig 0.13.0 · dart 3.12 · kotlin 2.1 ·
+scala 3.5.2 · lua 5.4 · ocaml 4.14 · ghc 9.4 · elixir 1.14 · clojure 1.12 ·
+swift 6.0.3. (`$SCALA3_LIB` = the Scala 3 dist `lib/` dir.)
+
+### Known prototype packaging nits (do not affect the 1325 result)
+
+* **swift** — top-level smoke code must live in `main.swift` (Swift compiles
+  top-level statements only there), hence the filename. Compile from the
+  `swift/` dir so `#filePath` resolves the corpus.
+* **clojure** — `provider.clj` declares ns `voxgig.proto.provider` (two path
+  segments) but `default-test-file` walks three dirs up (it assumes the file is
+  at `test/proto/clojure/`). Loading it by namespace from a staged classpath
+  where the file sits at `voxgig/proto/` therefore mis-resolves the corpus path.
+  Verified run (from a staged layout, with `/tmp/build -> <repo>/build`):
+
+  ```
+  mkdir -p /tmp/cljroot/voxgig/proto
+  cp test/proto/clojure/{provider,smoke}.clj /tmp/cljroot/voxgig/proto/
+  ln -sfn "$PWD/build" /tmp/build
+  cd /tmp/cljroot && clojure -Sdeps '{:paths ["."]}' -M -m voxgig.proto.smoke
+  ```
+
+  A cleaner fix (left for later): make `default-test-file` search upward for a
+  `build/test/test.json` rather than assuming a fixed depth.
diff --git a/test/proto/c/provider.h b/test/proto/c/provider.h
new file mode 100644
index 0000000..d652b5a
--- /dev/null
+++ b/test/proto/c/provider.h
@@ -0,0 +1,1278 @@
+/* Test Provider (prototype) — C11 port of the canonical ts/provider.ts.
+ *
+ * Reads the shared corpus (build/test/test.json) and hands test code clean,
+ * normalized cases. It is NOT a test runner: it never calls the subject and
+ * never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+ *
+ * DEPENDENCY-FREE and self-contained: this prototype ships its own minimal
+ * JSON parser and does NOT depend on the voxgig_struct C library. Only the C
+ * standard library (plus POSIX <regex.h> for regex helpers, standard on Linux).
+ *
+ * Single self-contained header-with-impl: define PROVIDER_IMPL in exactly one
+ * translation unit before including this header to pull in the implementation.
+ *
+ * Memory: this is a prototype. Parsed values and entries are arena-ish and
+ * intentionally leak rather than free; the contract is "crashing is not
+ * acceptable, leaking is".
+ *
+ * Corpus-path convention: provider_load(NULL) resolves to the relative path
+ * "build/test/test.json", which works when the process is run from the repo
+ * root. An absolute (or any explicit) path may be passed instead and is used
+ * verbatim.
+ */
+
+#ifndef PROVIDER_H
+#define PROVIDER_H
+
+#include <stdbool.h>
+#include <stddef.h>
+
+/* ─── JSON value model ─────────────────────────────────────────────────────
+ * Tagged union. Objects preserve key INSERTION ORDER: keys and values are
+ * stored in parallel arrays in parse order. */
+
+typedef enum {
+  JV_NULL = 0,
+  JV_BOOL,
+  JV_NUM,
+  JV_STR,
+  JV_ARR,
+  JV_OBJ
+} jv_type;
+
+typedef struct jvalue jvalue;
+
+struct jvalue {
+  jv_type type;
+  union {
+    bool b;     /* JV_BOOL */
+    double n;   /* JV_NUM  */
+    char* s;    /* JV_STR  (NUL-terminated, owned) */
+    struct {    /* JV_ARR  */
+      jvalue** items;
+      size_t len;
+      size_t cap;
+    } arr;
+    struct {    /* JV_OBJ  — parallel arrays, insertion order */
+      char** keys;
+      jvalue** vals;
+      size_t len;
+      size_t cap;
+    } obj;
+  } as;
+};
+
+/* Parse a NUL-terminated JSON string. Returns NULL on parse error. */
+jvalue* jv_parse(const char* text);
+/* Parse a whole file. Returns NULL on read or parse error. */
+jvalue* jv_parse_file(const char* path);
+
+/* Object key lookup honouring insertion order. Returns NULL if absent. */
+jvalue* jv_obj_get(const jvalue* o, const char* key);
+/* Key-presence test (distinct from "value is null"). */
+bool jv_obj_has(const jvalue* o, const char* key);
+
+/* Compact JSON serialization (owned, malloc'd). */
+char* jv_stringify(const jvalue* v);
+
+/* ─── Provider data model ──────────────────────────────────────────────────*/
+
+typedef enum { IN_IN = 0, IN_ARGS, IN_CTX } input_kind;
+typedef enum { EX_VALUE = 0, EX_ERROR, EX_MATCH, EX_ABSENT } expect_kind;
+
+typedef struct {
+  input_kind kind;
+  jvalue* in;    /* kind==IN_IN   — single arg; native null if "in" absent */
+  jvalue* args;  /* kind==IN_ARGS — positional vector (JV_ARR) */
+  jvalue* ctx;   /* kind==IN_CTX  — context map (JV_OBJ) */
+} Input;
+
+typedef struct {
+  bool any;
+  char* text;   /* may be NULL */
+  bool regex;
+} ErrorCheck;
+
+typedef struct {
+  expect_kind kind;
+  jvalue* value;       /* kind==VALUE — may be JV_NULL literal */
+  ErrorCheck error;    /* kind==ERROR */
+  jvalue* match;       /* kind==MATCH, or co-existing match block (else NULL) */
+} Expect;
+
+typedef struct {
+  const char* function;
+  const char* group;
+  int index;
+  char* id;       /* may be NULL */
+  bool doc;
+  char* client;   /* may be NULL */
+  Input input;
+  Expect expect;
+  jvalue* raw;    /* the original entry map, untouched */
+} Entry;
+
+typedef struct Provider Provider;
+
+/* Load the corpus. If path is NULL, resolves to "build/test/test.json"
+ * (relative to cwd — run from the repo root). Returns NULL on failure. */
+Provider* provider_load(const char* path);
+
+/* The parsed test.json (escape hatch). */
+jvalue* provider_raw(Provider* p);
+
+/* Ordered list of function names. *out_len receives the count. Owned by p. */
+const char** provider_functions(Provider* p, size_t* out_len);
+/* Ordered group names for fn. *out_len receives the count. Owned (leaked). */
+const char** provider_groups(Provider* p, const char* fn, size_t* out_len);
+/* Normalized entries for fn (all groups) or one group (group != NULL).
+ * *out_len receives the count. Returns a malloc'd array (leaked). */
+Entry* provider_entries(Provider* p, const char* fn, const char* group, size_t* out_len);
+
+/* ─── Pure comparison helpers (PROVIDER.md §5) ─────────────────────────────*/
+
+typedef struct {
+  bool ok;
+  char** path;       /* failure path components (NULL on ok) */
+  size_t path_len;
+  jvalue* expected;  /* NULL on ok */
+  jvalue* actual;    /* NULL on ok */
+} MatchResult;
+
+/* stringify(x): the string itself if x is JV_STR, else compact JSON. Owned. */
+char* provider_stringify(const jvalue* x);
+
+bool matchval(const jvalue* check, const jvalue* base);
+bool equal(const jvalue* expected, const jvalue* actual);
+bool equal_strict(const jvalue* expected, const jvalue* actual);
+MatchResult struct_match(const jvalue* check, const jvalue* base);
+bool error_matches(const ErrorCheck* check, const char* message);
+
+#endif /* PROVIDER_H */
+
+/* ════════════════════════════════════════════════════════════════════════ */
+#ifdef PROVIDER_IMPL
+
+#include <ctype.h>
+#include <regex.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define NULLMARK "__NULL__"
+#define UNDEFMARK "__UNDEF__"
+#define EXISTSMARK "__EXISTS__"
+
+/* ─── small allocation helpers ─────────────────────────────────────────────*/
+
+static void* xmalloc(size_t n) {
+  void* p = malloc(n ? n : 1);
+  if (!p) {
+    fprintf(stderr, "provider: out of memory\n");
+    abort();
+  }
+  return p;
+}
+
+static void* xrealloc(void* p, size_t n) {
+  void* q = realloc(p, n ? n : 1);
+  if (!q) {
+    fprintf(stderr, "provider: out of memory\n");
+    abort();
+  }
+  return q;
+}
+
+static char* xstrdup(const char* s) {
+  size_t n = strlen(s) + 1;
+  char* d = (char*)xmalloc(n);
+  memcpy(d, s, n);
+  return d;
+}
+
+/* ─── jvalue constructors ──────────────────────────────────────────────────*/
+
+static jvalue* jv_new(jv_type t) {
+  jvalue* v = (jvalue*)xmalloc(sizeof(jvalue));
+  memset(v, 0, sizeof(*v));
+  v->type = t;
+  return v;
+}
+
+static jvalue* jv_null(void) { return jv_new(JV_NULL); }
+
+static jvalue* jv_bool(bool b) {
+  jvalue* v = jv_new(JV_BOOL);
+  v->as.b = b;
+  return v;
+}
+
+static jvalue* jv_num(double n) {
+  jvalue* v = jv_new(JV_NUM);
+  v->as.n = n;
+  return v;
+}
+
+static jvalue* jv_str_owned(char* s) {
+  jvalue* v = jv_new(JV_STR);
+  v->as.s = s;
+  return v;
+}
+
+static void jv_arr_push(jvalue* a, jvalue* item) {
+  if (a->as.arr.len + 1 > a->as.arr.cap) {
+    size_t nc = a->as.arr.cap ? a->as.arr.cap * 2 : 8;
+    a->as.arr.items = (jvalue**)xrealloc(a->as.arr.items, nc * sizeof(jvalue*));
+    a->as.arr.cap = nc;
+  }
+  a->as.arr.items[a->as.arr.len++] = item;
+}
+
+static void jv_obj_put(jvalue* o, char* key /*owned*/, jvalue* val) {
+  if (o->as.obj.len + 1 > o->as.obj.cap) {
+    size_t nc = o->as.obj.cap ? o->as.obj.cap * 2 : 8;
+    o->as.obj.keys = (char**)xrealloc(o->as.obj.keys, nc * sizeof(char*));
+    o->as.obj.vals = (jvalue**)xrealloc(o->as.obj.vals, nc * sizeof(jvalue*));
+    o->as.obj.cap = nc;
+  }
+  o->as.obj.keys[o->as.obj.len] = key;
+  o->as.obj.vals[o->as.obj.len] = val;
+  o->as.obj.len++;
+}
+
+jvalue* jv_obj_get(const jvalue* o, const char* key) {
+  if (!o || o->type != JV_OBJ) {
+    return NULL;
+  }
+  for (size_t i = 0; i < o->as.obj.len; i++) {
+    if (strcmp(o->as.obj.keys[i], key) == 0) {
+      return o->as.obj.vals[i];
+    }
+  }
+  return NULL;
+}
+
+bool jv_obj_has(const jvalue* o, const char* key) {
+  if (!o || o->type != JV_OBJ) {
+    return false;
+  }
+  for (size_t i = 0; i < o->as.obj.len; i++) {
+    if (strcmp(o->as.obj.keys[i], key) == 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/* ─── recursive-descent JSON parser ────────────────────────────────────────*/
+
+typedef struct {
+  const char* p;
+  const char* end;
+  bool err;
+} jparser;
+
+static void jp_skip_ws(jparser* jp) {
+  while (jp->p < jp->end) {
+    char c = *jp->p;
+    if (c == ' ' || c == '\t' || c == '\n' || c == '\r') {
+      jp->p++;
+    } else {
+      break;
+    }
+  }
+}
+
+static jvalue* jp_value(jparser* jp);
+
+/* Append a code point to a growing UTF-8 buffer. */
+static void utf8_append(char** buf, size_t* len, size_t* cap, unsigned cp) {
+  char tmp[4];
+  size_t n;
+  if (cp < 0x80) {
+    tmp[0] = (char)cp;
+    n = 1;
+  } else if (cp < 0x800) {
+    tmp[0] = (char)(0xC0 | (cp >> 6));
+    tmp[1] = (char)(0x80 | (cp & 0x3F));
+    n = 2;
+  } else if (cp < 0x10000) {
+    tmp[0] = (char)(0xE0 | (cp >> 12));
+    tmp[1] = (char)(0x80 | ((cp >> 6) & 0x3F));
+    tmp[2] = (char)(0x80 | (cp & 0x3F));
+    n = 3;
+  } else {
+    tmp[0] = (char)(0xF0 | (cp >> 18));
+    tmp[1] = (char)(0x80 | ((cp >> 12) & 0x3F));
+    tmp[2] = (char)(0x80 | ((cp >> 6) & 0x3F));
+    tmp[3] = (char)(0x80 | (cp & 0x3F));
+    n = 4;
+  }
+  if (*len + n > *cap) {
+    size_t nc = *cap ? *cap * 2 : 16;
+    while (nc < *len + n) {
+      nc *= 2;
+    }
+    *buf = (char*)xrealloc(*buf, nc);
+    *cap = nc;
+  }
+  memcpy(*buf + *len, tmp, n);
+  *len += n;
+}
+
+static int hex4(const char* p) {
+  int v = 0;
+  for (int i = 0; i < 4; i++) {
+    char c = p[i];
+    int d;
+    if (c >= '0' && c <= '9') {
+      d = c - '0';
+    } else if (c >= 'a' && c <= 'f') {
+      d = c - 'a' + 10;
+    } else if (c >= 'A' && c <= 'F') {
+      d = c - 'A' + 10;
+    } else {
+      return -1;
+    }
+    v = (v << 4) | d;
+  }
+  return v;
+}
+
+/* Parse a string literal; jp->p must point at the opening quote. */
+static char* jp_string_raw(jparser* jp) {
+  if (jp->p >= jp->end || *jp->p != '"') {
+    jp->err = true;
+    return NULL;
+  }
+  jp->p++; /* opening quote */
+  char* buf = NULL;
+  size_t len = 0, cap = 0;
+  while (jp->p < jp->end) {
+    unsigned char c = (unsigned char)*jp->p;
+    if (c == '"') {
+      jp->p++;
+      /* ensure NUL-terminated */
+      if (len + 1 > cap) {
+        cap = cap ? cap + 1 : 1;
+        buf = (char*)xrealloc(buf, cap);
+      }
+      buf[len] = '\0';
+      return buf ? buf : xstrdup("");
+    }
+    if (c == '\\') {
+      jp->p++;
+      if (jp->p >= jp->end) {
+        jp->err = true;
+        return buf;
+      }
+      char e = *jp->p;
+      switch (e) {
+        case '"': utf8_append(&buf, &len, &cap, '"'); jp->p++; break;
+        case '\\': utf8_append(&buf, &len, &cap, '\\'); jp->p++; break;
+        case '/': utf8_append(&buf, &len, &cap, '/'); jp->p++; break;
+        case 'b': utf8_append(&buf, &len, &cap, '\b'); jp->p++; break;
+        case 'f': utf8_append(&buf, &len, &cap, '\f'); jp->p++; break;
+        case 'n': utf8_append(&buf, &len, &cap, '\n'); jp->p++; break;
+        case 'r': utf8_append(&buf, &len, &cap, '\r'); jp->p++; break;
+        case 't': utf8_append(&buf, &len, &cap, '\t'); jp->p++; break;
+        case 'u': {
+          jp->p++; /* past 'u' */
+          if (jp->p + 4 > jp->end) {
+            jp->err = true;
+            return buf;
+          }
+          int cp = hex4(jp->p);
+          if (cp < 0) {
+            jp->err = true;
+            return buf;
+          }
+          jp->p += 4;
+          unsigned u = (unsigned)cp;
+          /* surrogate pair */
+          if (u >= 0xD800 && u <= 0xDBFF && jp->p + 6 <= jp->end &&
+              jp->p[0] == '\\' && jp->p[1] == 'u') {
+            int lo = hex4(jp->p + 2);
+            if (lo >= 0xDC00 && lo <= 0xDFFF) {
+              u = 0x10000 + ((u - 0xD800) << 10) + ((unsigned)lo - 0xDC00);
+              jp->p += 6;
+            }
+          }
+          utf8_append(&buf, &len, &cap, u);
+          break;
+        }
+        default:
+          jp->err = true;
+          return buf;
+      }
+    } else {
+      utf8_append(&buf, &len, &cap, c);
+      jp->p++;
+    }
+  }
+  jp->err = true;
+  return buf;
+}
+
+static jvalue* jp_number(jparser* jp) {
+  const char* start = jp->p;
+  if (jp->p < jp->end && *jp->p == '-') {
+    jp->p++;
+  }
+  while (jp->p < jp->end && isdigit((unsigned char)*jp->p)) {
+    jp->p++;
+  }
+  if (jp->p < jp->end && *jp->p == '.') {
+    jp->p++;
+    while (jp->p < jp->end && isdigit((unsigned char)*jp->p)) {
+      jp->p++;
+    }
+  }
+  if (jp->p < jp->end && (*jp->p == 'e' || *jp->p == 'E')) {
+    jp->p++;
+    if (jp->p < jp->end && (*jp->p == '+' || *jp->p == '-')) {
+      jp->p++;
+    }
+    while (jp->p < jp->end && isdigit((unsigned char)*jp->p)) {
+      jp->p++;
+    }
+  }
+  size_t n = (size_t)(jp->p - start);
+  char* tmp = (char*)xmalloc(n + 1);
+  memcpy(tmp, start, n);
+  tmp[n] = '\0';
+  double d = strtod(tmp, NULL);
+  free(tmp);
+  return jv_num(d);
+}
+
+static bool jp_lit(jparser* jp, const char* word) {
+  size_t n = strlen(word);
+  if ((size_t)(jp->end - jp->p) < n || strncmp(jp->p, word, n) != 0) {
+    return false;
+  }
+  jp->p += n;
+  return true;
+}
+
+static jvalue* jp_array(jparser* jp) {
+  jp->p++; /* '[' */
+  jvalue* a = jv_new(JV_ARR);
+  jp_skip_ws(jp);
+  if (jp->p < jp->end && *jp->p == ']') {
+    jp->p++;
+    return a;
+  }
+  for (;;) {
+    jp_skip_ws(jp);
+    jvalue* item = jp_value(jp);
+    if (jp->err) {
+      return a;
+    }
+    jv_arr_push(a, item);
+    jp_skip_ws(jp);
+    if (jp->p >= jp->end) {
+      jp->err = true;
+      return a;
+    }
+    if (*jp->p == ',') {
+      jp->p++;
+      continue;
+    }
+    if (*jp->p == ']') {
+      jp->p++;
+      return a;
+    }
+    jp->err = true;
+    return a;
+  }
+}
+
+static jvalue* jp_object(jparser* jp) {
+  jp->p++; /* '{' */
+  jvalue* o = jv_new(JV_OBJ);
+  jp_skip_ws(jp);
+  if (jp->p < jp->end && *jp->p == '}') {
+    jp->p++;
+    return o;
+  }
+  for (;;) {
+    jp_skip_ws(jp);
+    if (jp->p >= jp->end || *jp->p != '"') {
+      jp->err = true;
+      return o;
+    }
+    char* key = jp_string_raw(jp);
+    if (jp->err) {
+      return o;
+    }
+    jp_skip_ws(jp);
+    if (jp->p >= jp->end || *jp->p != ':') {
+      jp->err = true;
+      return o;
+    }
+    jp->p++; /* ':' */
+    jp_skip_ws(jp);
+    jvalue* val = jp_value(jp);
+    if (jp->err) {
+      return o;
+    }
+    jv_obj_put(o, key, val);
+    jp_skip_ws(jp);
+    if (jp->p >= jp->end) {
+      jp->err = true;
+      return o;
+    }
+    if (*jp->p == ',') {
+      jp->p++;
+      continue;
+    }
+    if (*jp->p == '}') {
+      jp->p++;
+      return o;
+    }
+    jp->err = true;
+    return o;
+  }
+}
+
+static jvalue* jp_value(jparser* jp) {
+  jp_skip_ws(jp);
+  if (jp->p >= jp->end) {
+    jp->err = true;
+    return jv_null();
+  }
+  char c = *jp->p;
+  switch (c) {
+    case '{': return jp_object(jp);
+    case '[': return jp_array(jp);
+    case '"': {
+      char* s = jp_string_raw(jp);
+      if (jp->err) {
+        return jv_null();
+      }
+      return jv_str_owned(s);
+    }
+    case 't':
+      if (jp_lit(jp, "true")) {
+        return jv_bool(true);
+      }
+      jp->err = true;
+      return jv_null();
+    case 'f':
+      if (jp_lit(jp, "false")) {
+        return jv_bool(false);
+      }
+      jp->err = true;
+      return jv_null();
+    case 'n':
+      if (jp_lit(jp, "null")) {
+        return jv_null();
+      }
+      jp->err = true;
+      return jv_null();
+    default:
+      if (c == '-' || isdigit((unsigned char)c)) {
+        return jp_number(jp);
+      }
+      jp->err = true;
+      return jv_null();
+  }
+}
+
+jvalue* jv_parse(const char* text) {
+  jparser jp;
+  jp.p = text;
+  jp.end = text + strlen(text);
+  jp.err = false;
+  jvalue* v = jp_value(&jp);
+  if (jp.err) {
+    return NULL;
+  }
+  jp_skip_ws(&jp);
+  /* trailing junk is tolerated leniently for prototype robustness */
+  return v;
+}
+
+jvalue* jv_parse_file(const char* path) {
+  FILE* f = fopen(path, "rb");
+  if (!f) {
+    return NULL;
+  }
+  if (fseek(f, 0, SEEK_END) != 0) {
+    fclose(f);
+    return NULL;
+  }
+  long sz = ftell(f);
+  if (sz < 0) {
+    fclose(f);
+    return NULL;
+  }
+  rewind(f);
+  char* buf = (char*)xmalloc((size_t)sz + 1);
+  size_t rd = fread(buf, 1, (size_t)sz, f);
+  fclose(f);
+  buf[rd] = '\0';
+  jvalue* v = jv_parse(buf);
+  free(buf);
+  return v;
+}
+
+/* ─── compact JSON serialization ───────────────────────────────────────────*/
+
+typedef struct {
+  char* buf;
+  size_t len;
+  size_t cap;
+} sbuf;
+
+static void sb_putc(sbuf* sb, char c) {
+  if (sb->len + 1 > sb->cap) {
+    size_t nc = sb->cap ? sb->cap * 2 : 32;
+    sb->buf = (char*)xrealloc(sb->buf, nc);
+    sb->cap = nc;
+  }
+  sb->buf[sb->len++] = c;
+}
+
+static void sb_puts(sbuf* sb, const char* s) {
+  for (; *s; s++) {
+    sb_putc(sb, *s);
+  }
+}
+
+static void sb_json_str(sbuf* sb, const char* s) {
+  sb_putc(sb, '"');
+  for (const unsigned char* p = (const unsigned char*)s; *p; p++) {
+    unsigned char c = *p;
+    switch (c) {
+      case '"': sb_puts(sb, "\\\""); break;
+      case '\\': sb_puts(sb, "\\\\"); break;
+      case '\b': sb_puts(sb, "\\b"); break;
+      case '\f': sb_puts(sb, "\\f"); break;
+      case '\n': sb_puts(sb, "\\n"); break;
+      case '\r': sb_puts(sb, "\\r"); break;
+      case '\t': sb_puts(sb, "\\t"); break;
+      default:
+        if (c < 0x20) {
+          char tmp[8];
+          snprintf(tmp, sizeof(tmp), "\\u%04x", c);
+          sb_puts(sb, tmp);
+        } else {
+          sb_putc(sb, (char)c);
+        }
+    }
+  }
+  sb_putc(sb, '"');
+}
+
+/* Render a number the way JS JSON.stringify would for these corpus values:
+ * integers without a decimal point, otherwise %g-ish. */
+static void sb_json_num(sbuf* sb, double n) {
+  char tmp[64];
+  if (n == (double)(long long)n && n >= -9.007199254740992e15 &&
+      n <= 9.007199254740992e15) {
+    snprintf(tmp, sizeof(tmp), "%lld", (long long)n);
+  } else {
+    snprintf(tmp, sizeof(tmp), "%.17g", n);
+  }
+  sb_puts(sb, tmp);
+}
+
+static void sb_json(sbuf* sb, const jvalue* v) {
+  if (!v) {
+    sb_puts(sb, "null");
+    return;
+  }
+  switch (v->type) {
+    case JV_NULL: sb_puts(sb, "null"); break;
+    case JV_BOOL: sb_puts(sb, v->as.b ? "true" : "false"); break;
+    case JV_NUM: sb_json_num(sb, v->as.n); break;
+    case JV_STR: sb_json_str(sb, v->as.s); break;
+    case JV_ARR:
+      sb_putc(sb, '[');
+      for (size_t i = 0; i < v->as.arr.len; i++) {
+        if (i) {
+          sb_putc(sb, ',');
+        }
+        sb_json(sb, v->as.arr.items[i]);
+      }
+      sb_putc(sb, ']');
+      break;
+    case JV_OBJ:
+      sb_putc(sb, '{');
+      for (size_t i = 0; i < v->as.obj.len; i++) {
+        if (i) {
+          sb_putc(sb, ',');
+        }
+        sb_json_str(sb, v->as.obj.keys[i]);
+        sb_putc(sb, ':');
+        sb_json(sb, v->as.obj.vals[i]);
+      }
+      sb_putc(sb, '}');
+      break;
+  }
+}
+
+char* jv_stringify(const jvalue* v) {
+  sbuf sb = {0};
+  sb_json(&sb, v);
+  sb_putc(&sb, '\0');
+  return sb.buf;
+}
+
+/* ─── Provider ─────────────────────────────────────────────────────────────*/
+
+struct Provider {
+  jvalue* spec;
+};
+
+/* The root holding functions: spec.struct if present, else spec. */
+static jvalue* prov_root(Provider* p) {
+  jvalue* root = jv_obj_get(p->spec, "struct");
+  return root ? root : p->spec;
+}
+
+static bool is_group_bag(const jvalue* v) {
+  if (!v || v->type != JV_OBJ) {
+    return false;
+  }
+  jvalue* set = jv_obj_get(v, "set");
+  return set && set->type == JV_ARR;
+}
+
+static bool has_groups(const jvalue* v) {
+  if (!v || v->type != JV_OBJ) {
+    return false;
+  }
+  for (size_t i = 0; i < v->as.obj.len; i++) {
+    if (strcmp(v->as.obj.keys[i], "name") != 0 && is_group_bag(v->as.obj.vals[i])) {
+      return true;
+    }
+  }
+  return false;
+}
+
+static jvalue* fn_node(Provider* p, const char* fn) {
+  jvalue* root = jv_obj_get(p->spec, "struct");
+  jvalue* node = NULL;
+  if (root) {
+    node = jv_obj_get(root, fn);
+  }
+  if (!node) {
+    node = jv_obj_get(p->spec, fn);
+  }
+  return node;
+}
+
+Provider* provider_load(const char* path) {
+  const char* file = path ? path : "build/test/test.json";
+  jvalue* spec = jv_parse_file(file);
+  if (!spec) {
+    return NULL;
+  }
+  Provider* p = (Provider*)xmalloc(sizeof(Provider));
+  p->spec = spec;
+  return p;
+}
+
+jvalue* provider_raw(Provider* p) { return p->spec; }
+
+const char** provider_functions(Provider* p, size_t* out_len) {
+  jvalue* root = prov_root(p);
+  const char** out = (const char**)xmalloc(root->as.obj.len * sizeof(char*));
+  size_t n = 0;
+  for (size_t i = 0; i < root->as.obj.len; i++) {
+    jvalue* v = root->as.obj.vals[i];
+    if (is_group_bag(v) || has_groups(v)) {
+      out[n++] = root->as.obj.keys[i];
+    }
+  }
+  *out_len = n;
+  return out;
+}
+
+const char** provider_groups(Provider* p, const char* fn, size_t* out_len) {
+  jvalue* node = fn_node(p, fn);
+  if (!node || node->type != JV_OBJ) {
+    *out_len = 0;
+    return NULL;
+  }
+  const char** out = (const char**)xmalloc(node->as.obj.len * sizeof(char*));
+  size_t n = 0;
+  for (size_t i = 0; i < node->as.obj.len; i++) {
+    if (strcmp(node->as.obj.keys[i], "name") != 0 && is_group_bag(node->as.obj.vals[i])) {
+      out[n++] = node->as.obj.keys[i];
+    }
+  }
+  *out_len = n;
+  return out;
+}
+
+static ErrorCheck parse_err(const jvalue* err) {
+  ErrorCheck ec = {true, NULL, false};
+  if (err && err->type == JV_BOOL && err->as.b) {
+    ec.any = true;
+    ec.text = NULL;
+    ec.regex = false;
+    return ec;
+  }
+  if (err && err->type == JV_STR) {
+    const char* s = err->as.s;
+    size_t len = strlen(s);
+    /* /re/  matches ^/(.+)/$ */
+    if (len >= 3 && s[0] == '/' && s[len - 1] == '/') {
+      ec.any = false;
+      ec.regex = true;
+      size_t inner = len - 2;
+      char* t = (char*)xmalloc(inner + 1);
+      memcpy(t, s + 1, inner);
+      t[inner] = '\0';
+      ec.text = t;
+      return ec;
+    }
+    ec.any = false;
+    ec.regex = false;
+    ec.text = xstrdup(s);
+    return ec;
+  }
+  /* non-true, non-string err spec: treat as "any error" */
+  ec.any = true;
+  ec.text = NULL;
+  ec.regex = false;
+  return ec;
+}
+
+static Input resolve_input(const jvalue* raw) {
+  Input in;
+  memset(&in, 0, sizeof(in));
+  if (jv_obj_has(raw, "ctx")) {
+    in.kind = IN_CTX;
+    in.ctx = jv_obj_get(raw, "ctx");
+    return in;
+  }
+  if (jv_obj_has(raw, "args")) {
+    in.kind = IN_ARGS;
+    in.args = jv_obj_get(raw, "args");
+    return in;
+  }
+  in.kind = IN_IN;
+  in.in = jv_obj_has(raw, "in") ? jv_obj_get(raw, "in") : jv_null();
+  return in;
+}
+
+static Expect resolve_expect(const jvalue* raw) {
+  Expect ex;
+  memset(&ex, 0, sizeof(ex));
+  jvalue* match_part = jv_obj_has(raw, "match") ? jv_obj_get(raw, "match") : NULL;
+  if (jv_obj_has(raw, "err")) {
+    ex.kind = EX_ERROR;
+    ex.error = parse_err(jv_obj_get(raw, "err"));
+    ex.match = match_part;
+    return ex;
+  }
+  if (jv_obj_has(raw, "out")) {
+    ex.kind = EX_VALUE;
+    ex.value = jv_obj_get(raw, "out");
+    ex.match = match_part;
+    return ex;
+  }
+  if (jv_obj_has(raw, "match")) {
+    ex.kind = EX_MATCH;
+    ex.match = jv_obj_get(raw, "match");
+    return ex;
+  }
+  ex.kind = EX_ABSENT;
+  return ex;
+}
+
+static const char* group_client(Provider* p, const char* fn, const char* group);
+
+static Entry normalize_entry(Provider* p, const char* fn, const char* group, int index,
+                             jvalue* raw) {
+  Entry e;
+  memset(&e, 0, sizeof(e));
+  e.function = fn;
+  e.group = group;
+  e.index = index;
+  jvalue* idv = jv_obj_get(raw, "id");
+  e.id = (idv && idv->type == JV_STR) ? xstrdup(idv->as.s)
+       : (idv && idv->type != JV_NULL) ? jv_stringify(idv)
+       : NULL;
+  jvalue* docv = jv_obj_get(raw, "doc");
+  e.doc = (docv && docv->type == JV_BOOL && docv->as.b);
+  jvalue* clientv = jv_obj_get(raw, "client");
+  e.client = (clientv && clientv->type == JV_STR) ? xstrdup(clientv->as.s)
+           : (clientv && clientv->type != JV_NULL) ? jv_stringify(clientv)
+           : NULL;
+  /* If the entry itself names no client, fall back to the group's DEF.client. */
+  if (!e.client) {
+    const char* gc = group_client(p, fn, group);
+    if (gc) {
+      e.client = xstrdup(gc);
+    }
+  }
+  e.input = resolve_input(raw);
+  e.expect = resolve_expect(raw);
+  e.raw = raw;
+  return e;
+}
+
+/* The named client from the group's DEF.client (or NULL). */
+static const char* group_client(Provider* p, const char* fn, const char* group) {
+  jvalue* node = fn_node(p, fn);
+  if (!node) {
+    return NULL;
+  }
+  jvalue* bag = jv_obj_get(node, group);
+  if (!bag || bag->type != JV_OBJ) {
+    return NULL;
+  }
+  jvalue* def = jv_obj_get(bag, "DEF");
+  if (!def || def->type != JV_OBJ) {
+    return NULL;
+  }
+  jvalue* client = jv_obj_get(def, "client");
+  if (client && client->type == JV_STR) {
+    return client->as.s;
+  }
+  return NULL;
+}
+
+Entry* provider_entries(Provider* p, const char* fn, const char* group, size_t* out_len) {
+  jvalue* node = fn_node(p, fn);
+  if (!node || node->type != JV_OBJ) {
+    *out_len = 0;
+    return NULL;
+  }
+  size_t ng = 0;
+  const char** groups;
+  if (group) {
+    static const char* one[1];
+    one[0] = group;
+    groups = one;
+    ng = 1;
+  } else {
+    groups = provider_groups(p, fn, &ng);
+  }
+  Entry* out = NULL;
+  size_t len = 0, cap = 0;
+  for (size_t gi = 0; gi < ng; gi++) {
+    jvalue* bag = jv_obj_get(node, groups[gi]);
+    if (!is_group_bag(bag)) {
+      continue;
+    }
+    jvalue* set = jv_obj_get(bag, "set");
+    for (size_t i = 0; i < set->as.arr.len; i++) {
+      if (len + 1 > cap) {
+        cap = cap ? cap * 2 : 16;
+        out = (Entry*)xrealloc(out, cap * sizeof(Entry));
+      }
+      out[len++] = normalize_entry(p, fn, groups[gi], (int)i, set->as.arr.items[i]);
+    }
+  }
+  *out_len = len;
+  return out;
+}
+
+/* ─── pure comparison helpers ──────────────────────────────────────────────*/
+
+char* provider_stringify(const jvalue* x) {
+  if (x && x->type == JV_STR) {
+    return xstrdup(x->as.s);
+  }
+  return jv_stringify(x);
+}
+
+static bool jv_shallow_eq(const jvalue* a, const jvalue* b) {
+  /* identity-ish equality for scalars (mirrors === for primitives) */
+  if (a == b) {
+    return true;
+  }
+  if (!a || !b) {
+    return false;
+  }
+  if (a->type != b->type) {
+    return false;
+  }
+  switch (a->type) {
+    case JV_NULL: return true;
+    case JV_BOOL: return a->as.b == b->as.b;
+    case JV_NUM: return a->as.n == b->as.n;
+    case JV_STR: return strcmp(a->as.s, b->as.s) == 0;
+    default: return false; /* arrays/objects are never === */
+  }
+}
+
+/* normNull / normMark: produce a normalized copy. We don't materialize a copy;
+ * instead deep_eq carries a flag for how to treat the NULLMARK string and
+ * (lenient only) treat null/missing uniformly. Simpler: implement equality
+ * with normalization inline. */
+
+static bool is_nullmark(const jvalue* v) {
+  return v && v->type == JV_STR && strcmp(v->as.s, NULLMARK) == 0;
+}
+
+/* lenient: NULLMARK and null collapse to the same nullish.
+ * strict: only NULLMARK -> null; (undefined != null, but our model has no
+ * "undefined" — absent keys already became jv_null in resolve_input, and the
+ * corpus expectation values come straight from JSON, so strict simply does not
+ * collapse a real null against a NULLMARK string differently from lenient here;
+ * the meaningful distinction strict draws is that it does NOT treat a missing
+ * key as null. In this value model both are represented, so strict == lenient
+ * for materialized values except we keep the NULLMARK normalization.) */
+
+static bool deep_eq(const jvalue* a, const jvalue* b, bool lenient) {
+  /* Normalize NULLMARK->null (both modes) and, in lenient mode, null/absent. */
+  bool an = is_nullmark(a) || (lenient && (!a || (a && a->type == JV_NULL)));
+  bool bn = is_nullmark(b) || (lenient && (!b || (b && b->type == JV_NULL)));
+  if (an || bn) {
+    /* In strict mode a JV_NULL is itself; treat as null only via NULLMARK. */
+    if (lenient) {
+      return an == bn;
+    }
+    /* strict: NULLMARK normalizes to null; compare normalized nullness */
+    bool a_null = is_nullmark(a) || (a && a->type == JV_NULL);
+    bool b_null = is_nullmark(b) || (b && b->type == JV_NULL);
+    if (a_null || b_null) {
+      return a_null == b_null;
+    }
+  }
+  if (!a || !b) {
+    return a == b;
+  }
+  if (a->type != b->type) {
+    return false;
+  }
+  switch (a->type) {
+    case JV_NULL: return true;
+    case JV_BOOL: return a->as.b == b->as.b;
+    case JV_NUM: return a->as.n == b->as.n;
+    case JV_STR: return strcmp(a->as.s, b->as.s) == 0;
+    case JV_ARR: {
+      if (a->as.arr.len != b->as.arr.len) {
+        return false;
+      }
+      for (size_t i = 0; i < a->as.arr.len; i++) {
+        if (!deep_eq(a->as.arr.items[i], b->as.arr.items[i], lenient)) {
+          return false;
+        }
+      }
+      return true;
+    }
+    case JV_OBJ: {
+      if (a->as.obj.len != b->as.obj.len) {
+        return false;
+      }
+      for (size_t i = 0; i < a->as.obj.len; i++) {
+        jvalue* bv = jv_obj_get(b, a->as.obj.keys[i]);
+        if (!jv_obj_has(b, a->as.obj.keys[i])) {
+          return false;
+        }
+        if (!deep_eq(a->as.obj.vals[i], bv, lenient)) {
+          return false;
+        }
+      }
+      return true;
+    }
+  }
+  return false;
+}
+
+bool equal(const jvalue* expected, const jvalue* actual) {
+  return deep_eq(expected, actual, true);
+}
+
+bool equal_strict(const jvalue* expected, const jvalue* actual) {
+  return deep_eq(expected, actual, false);
+}
+
+bool matchval(const jvalue* check, const jvalue* base) {
+  if (jv_shallow_eq(check, base)) {
+    return true;
+  }
+  if (check && check->type == JV_STR) {
+    char* basestr = provider_stringify(base);
+    const char* cs = check->as.s;
+    size_t clen = strlen(cs);
+    bool result;
+    if (clen >= 3 && cs[0] == '/' && cs[clen - 1] == '/') {
+      /* /re/ */
+      size_t inner = clen - 2;
+      char* re = (char*)xmalloc(inner + 1);
+      memcpy(re, cs + 1, inner);
+      re[inner] = '\0';
+      regex_t rx;
+      if (regcomp(&rx, re, REG_EXTENDED) == 0) {
+        result = (regexec(&rx, basestr, 0, NULL, 0) == 0);
+        regfree(&rx);
+      } else {
+        result = false;
+      }
+      free(re);
+    } else {
+      /* case-insensitive substring */
+      char* lb = xstrdup(basestr);
+      char* lc = xstrdup(cs);
+      for (char* q = lb; *q; q++) {
+        *q = (char)tolower((unsigned char)*q);
+      }
+      for (char* q = lc; *q; q++) {
+        *q = (char)tolower((unsigned char)*q);
+      }
+      result = (strstr(lb, lc) != NULL);
+      free(lb);
+      free(lc);
+    }
+    free(basestr);
+    return result;
+  }
+  /* check is a function -> true; we have no function values, so false. */
+  return false;
+}
+
+bool error_matches(const ErrorCheck* check, const char* message) {
+  if (check->any) {
+    return true;
+  }
+  if (!check->text) {
+    return false;
+  }
+  if (!message) {
+    message = "";
+  }
+  if (check->regex) {
+    regex_t rx;
+    if (regcomp(&rx, check->text, REG_EXTENDED) != 0) {
+      return false;
+    }
+    bool m = (regexec(&rx, message, 0, NULL, 0) == 0);
+    regfree(&rx);
+    return m;
+  }
+  char* lm = xstrdup(message);
+  char* lt = xstrdup(check->text);
+  for (char* q = lm; *q; q++) {
+    *q = (char)tolower((unsigned char)*q);
+  }
+  for (char* q = lt; *q; q++) {
+    *q = (char)tolower((unsigned char)*q);
+  }
+  bool m = (strstr(lm, lt) != NULL);
+  free(lm);
+  free(lt);
+  return m;
+}
+
+/* getpath over the jvalue model; returns NULL if absent. */
+static jvalue* jv_getpath(jvalue* store, char** path, size_t plen) {
+  jvalue* cur = store;
+  for (size_t i = 0; i < plen; i++) {
+    if (!cur) {
+      return NULL;
+    }
+    if (cur->type == JV_ARR) {
+      char* endp = NULL;
+      long idx = strtol(path[i], &endp, 10);
+      if (endp == path[i] || idx < 0 || (size_t)idx >= cur->as.arr.len) {
+        return NULL;
+      }
+      cur = cur->as.arr.items[idx];
+    } else if (cur->type == JV_OBJ) {
+      cur = jv_obj_get(cur, path[i]);
+    } else {
+      return NULL;
+    }
+  }
+  return cur;
+}
+
+static bool jv_is_node(const jvalue* v) {
+  return v && (v->type == JV_OBJ || v->type == JV_ARR);
+}
+
+typedef struct {
+  bool ok;
+  char** path;
+  size_t path_len;
+  jvalue* expected;
+  jvalue* actual;
+} sm_state;
+
+static void walk_leaves(jvalue* node, char** path, size_t plen, jvalue* base, sm_state* st);
+
+static void sm_check_leaf(jvalue* val, char** path, size_t plen, jvalue* base, sm_state* st) {
+  if (!st->ok) {
+    return;
+  }
+  jvalue* baseval = jv_getpath(base, path, plen);
+  if (jv_shallow_eq(val, baseval)) {
+    return;
+  }
+  if (val && val->type == JV_STR && strcmp(val->as.s, UNDEFMARK) == 0 && baseval == NULL) {
+    return;
+  }
+  if (val && val->type == JV_STR && strcmp(val->as.s, EXISTSMARK) == 0 && baseval &&
+      baseval->type != JV_NULL) {
+    return;
+  }
+  if (!matchval(val, baseval)) {
+    st->ok = false;
+    /* copy the path */
+    char** pc = (char**)xmalloc((plen ? plen : 1) * sizeof(char*));
+    for (size_t i = 0; i < plen; i++) {
+      pc[i] = xstrdup(path[i]);
+    }
+    st->path = pc;
+    st->path_len = plen;
+    st->expected = val;
+    st->actual = baseval;
+  }
+}
+
+static void walk_leaves(jvalue* node, char** path, size_t plen, jvalue* base, sm_state* st) {
+  if (!st->ok) {
+    return;
+  }
+  if (node && node->type == JV_ARR) {
+    for (size_t i = 0; i < node->as.arr.len; i++) {
+      char idxbuf[32];
+      snprintf(idxbuf, sizeof(idxbuf), "%zu", i);
+      char** np = (char**)xmalloc((plen + 1) * sizeof(char*));
+      for (size_t k = 0; k < plen; k++) {
+        np[k] = path[k];
+      }
+      np[plen] = idxbuf;
+      walk_leaves(node->as.arr.items[i], np, plen + 1, base, st);
+      free(np);
+    }
+  } else if (jv_is_node(node)) {
+    for (size_t i = 0; i < node->as.obj.len; i++) {
+      char** np = (char**)xmalloc((plen + 1) * sizeof(char*));
+      for (size_t k = 0; k < plen; k++) {
+        np[k] = path[k];
+      }
+      np[plen] = node->as.obj.keys[i];
+      walk_leaves(node->as.obj.vals[i], np, plen + 1, base, st);
+      free(np);
+    }
+  } else {
+    sm_check_leaf(node, path, plen, base, st);
+  }
+}
+
+MatchResult struct_match(const jvalue* check, const jvalue* base) {
+  sm_state st;
+  memset(&st, 0, sizeof(st));
+  st.ok = true;
+  walk_leaves((jvalue*)check, NULL, 0, (jvalue*)base, &st);
+  MatchResult r;
+  r.ok = st.ok;
+  r.path = st.path;
+  r.path_len = st.path_len;
+  r.expected = st.expected;
+  r.actual = st.actual;
+  return r;
+}
+
+#endif /* PROVIDER_IMPL */
diff --git a/test/proto/c/smoke.c b/test/proto/c/smoke.c
new file mode 100644
index 0000000..864304d
--- /dev/null
+++ b/test/proto/c/smoke.c
@@ -0,0 +1,106 @@
+/* Smoke test for the C test provider port. Prints summary stats that must
+ * match the canonical TS output documented in PROVIDER.md.
+ *
+ * Build & run (from the repo root so the relative corpus path resolves):
+ *   gcc -std=c11 -O2 test/proto/c/smoke.c -o /tmp/c_smoke -lm
+ *   ./...  (run from /home/user/struct)
+ *
+ * An explicit corpus path may be passed as argv[1].
+ */
+
+#define PROVIDER_IMPL
+#include "provider.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static const char* input_kind_name(input_kind k) {
+  switch (k) {
+    case IN_IN: return "in";
+    case IN_ARGS: return "args";
+    case IN_CTX: return "ctx";
+  }
+  return "?";
+}
+
+static const char* expect_kind_name(expect_kind k) {
+  switch (k) {
+    case EX_VALUE: return "value";
+    case EX_ERROR: return "error";
+    case EX_MATCH: return "match";
+    case EX_ABSENT: return "absent";
+  }
+  return "?";
+}
+
+int main(int argc, char** argv) {
+  const char* path = argc > 1 ? argv[1] : NULL;
+  Provider* prov = provider_load(path);
+  if (!prov) {
+    fprintf(stderr, "failed to load corpus (%s)\n",
+            path ? path : "build/test/test.json");
+    return 1;
+  }
+
+  size_t nfns = 0;
+  const char** fns = provider_functions(prov, &nfns);
+  printf("functions: ");
+  for (size_t i = 0; i < nfns; i++) {
+    printf("%s%s", i ? ", " : "", fns[i]);
+  }
+  printf("\n");
+
+  int total = 0;
+  /* expect kinds in fixed order: value, error, match, absent */
+  int ev = 0, ee = 0, em = 0, ea = 0;
+  /* input kinds: in, args, ctx */
+  int ii = 0, ia = 0, ic = 0;
+
+  for (size_t f = 0; f < nfns; f++) {
+    size_t ne = 0;
+    Entry* entries = provider_entries(prov, fns[f], NULL, &ne);
+    for (size_t e = 0; e < ne; e++) {
+      total++;
+      switch (entries[e].expect.kind) {
+        case EX_VALUE: ev++; break;
+        case EX_ERROR: ee++; break;
+        case EX_MATCH: em++; break;
+        case EX_ABSENT: ea++; break;
+      }
+      switch (entries[e].input.kind) {
+        case IN_IN: ii++; break;
+        case IN_ARGS: ia++; break;
+        case IN_CTX: ic++; break;
+      }
+    }
+  }
+
+  printf("total entries: %d ; ", total);
+  printf("expect kinds: value=%d, absent=%d, match=%d, error=%d ; ", ev, ea, em, ee);
+  printf("input kinds: in=%d", ii);
+  if (ia) {
+    printf(", args=%d", ia);
+  }
+  if (ic) {
+    printf(", ctx=%d", ic);
+  }
+  printf("\n");
+
+  size_t ne = 0;
+  Entry* gp = provider_entries(prov, "getpath", "basic", &ne);
+  if (ne > 0) {
+    Entry* e = &gp[0];
+    char* val = e->expect.value ? jv_stringify(e->expect.value) : NULL;
+    const char* valstr = val ? val : "(none)";
+    printf("getpath/basic[0]: id=%s, doc=%s, input.kind=%s, expect.kind=%s, expect.value=%s\n",
+           e->id ? e->id : "(null)",
+           e->doc ? "true" : "false",
+           input_kind_name(e->input.kind),
+           expect_kind_name(e->expect.kind),
+           valstr);
+    free(val);
+  }
+
+  return 0;
+}
diff --git a/test/proto/clojure/provider.clj b/test/proto/clojure/provider.clj
new file mode 100644
index 0000000..2b2d352
--- /dev/null
+++ b/test/proto/clojure/provider.clj
@@ -0,0 +1,486 @@
+;; Test Provider (prototype) — Clojure port of the canonical ts/provider.ts.
+;;
+;; Reads the shared corpus (build/test/test.json) and hands test code clean,
+;; normalized cases. It is NOT a test runner: it never calls the subject and
+;; never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+;;
+;; Zero runtime dependencies (Clojure / Java stdlib only). This includes a
+;; hand-written, minimal JSON reader — no clojure.data.json, no cheshire.
+;;
+;; ─── Data model produced by the JSON reader ────────────────────────────────
+;;
+;;   JSON object  -> a Clojure persistent map. Key INSERTION ORDER is preserved
+;;                   by attaching it as metadata under :order (a vector of the
+;;                   string keys). The map value itself is an ordinary Clojure
+;;                   map so get / contains? / deep-equality work idiomatically;
+;;                   `okeys` reads :order to recover JSON order (needed so that
+;;                   functions()/groups() report keys in corpus order).
+;;   JSON array   -> a Clojure vector.
+;;   JSON string  -> java.lang.String.
+;;   JSON number  -> Long (integral) or Double (has . / e / E).
+;;   JSON true/false -> Boolean.
+;;   JSON null    -> the keyword ::null  (a DISTINCT sentinel, kept separate
+;;                   from Clojure nil which we reserve for "key absent").
+;;
+;; The ::null choice mirrors the TS provider keeping VALUE(null) distinct from
+;; ABSENT: a present "out": null becomes {:kind :value :value ::null}, whereas
+;; a missing "out" key becomes {:kind :absent}.
+
+(ns voxgig.proto.provider
+  (:refer-clojure :exclude [load])
+  (:require [clojure.string :as str])
+  (:import [java.util.regex Pattern]))
+
+(def NULLMARK "__NULL__")
+(def UNDEFMARK "__UNDEF__")
+(def EXISTSMARK "__EXISTS__")
+
+;; Distinct sentinel for JSON null (separate from Clojure nil = "absent").
+(def JNULL ::null)
+
+;; Sentinel distinguishing "key absent" from a present value during getpath.
+(def MISSING ::missing)
+
+;; ───────────────────────────────────────────────────────────────────────────
+;; Ordered-map helpers
+;; ───────────────────────────────────────────────────────────────────────────
+
+(defn ordered-map
+  "Build a Clojure map from a seq of [k v] pairs, recording insertion order
+   in :order metadata so JSON key order can be recovered later."
+  [pairs]
+  (let [m (reduce (fn [acc [k v]] (assoc acc k v)) {} pairs)]
+    (with-meta m {:order (mapv first pairs)})))
+
+(defn okeys
+  "Keys of an object map in JSON insertion order (falls back to (keys m))."
+  [m]
+  (or (:order (meta m)) (vec (keys m))))
+
+(defn omap?
+  "Is v a JSON object (a Clojure map)?"
+  [v]
+  (map? v))
+
+;; ───────────────────────────────────────────────────────────────────────────
+;; Minimal JSON reader -> ordered maps / vectors / Long / Double / String /
+;; Boolean / JNULL
+;; ───────────────────────────────────────────────────────────────────────────
+
+(defn json-read [^String s]
+  (let [n (count s)
+        pos (int-array 1)]
+    (letfn [(peek-c [] (when (< (aget pos 0) n) (.charAt s (aget pos 0))))
+            (next-c [] (let [c (.charAt s (aget pos 0))]
+                         (aset pos 0 (inc (aget pos 0))) c))
+            (skip-ws []
+              (while (and (< (aget pos 0) n)
+                          (Character/isWhitespace (.charAt s (aget pos 0))))
+                (aset pos 0 (inc (aget pos 0)))))
+            (parse-val []
+              (skip-ws)
+              (let [c (peek-c)]
+                (cond
+                  (= c \{) (parse-obj)
+                  (= c \[) (parse-arr)
+                  (= c \") (parse-str)
+                  (or (= c \t) (= c \f)) (parse-bool)
+                  (= c \n) (parse-null)
+                  :else (parse-num))))
+            (parse-obj []
+              (next-c) ;; consume {
+              (skip-ws)
+              (if (= (peek-c) \})
+                (do (next-c) (ordered-map []))
+                (loop [acc (transient [])]
+                  (skip-ws)
+                  (let [k (parse-str)]
+                    (skip-ws)
+                    (next-c) ;; consume :
+                    (let [v (parse-val)
+                          acc (conj! acc [k v])]
+                      (skip-ws)
+                      (let [c (next-c)]
+                        (if (= c \,)
+                          (recur acc)
+                          (ordered-map (persistent! acc)))))))))
+            (parse-arr []
+              (next-c) ;; consume [
+              (skip-ws)
+              (if (= (peek-c) \])
+                (do (next-c) [])
+                (loop [acc (transient [])]
+                  (let [v (parse-val)
+                        acc (conj! acc v)]
+                    (skip-ws)
+                    (let [c (next-c)]
+                      (if (= c \,)
+                        (recur acc)
+                        (persistent! acc)))))))
+            (parse-str []
+              (next-c) ;; consume opening "
+              (let [sb (StringBuilder.)]
+                (loop []
+                  (let [c (next-c)]
+                    (cond
+                      (= c \") (.toString sb)
+                      (= c \\)
+                      (let [e (next-c)]
+                        (case e
+                          \" (.append sb \")
+                          \\ (.append sb \\)
+                          \/ (.append sb \/)
+                          \n (.append sb \newline)
+                          \t (.append sb \tab)
+                          \r (.append sb \return)
+                          \b (.append sb \backspace)
+                          \f (.append sb \formfeed)
+                          \u (let [hex (subs s (aget pos 0) (+ (aget pos 0) 4))]
+                               (aset pos 0 (+ (aget pos 0) 4))
+                               (.append sb (char (Integer/parseInt hex 16))))
+                          (.append sb e))
+                        (recur))
+                      :else (do (.append sb c) (recur)))))))
+            (parse-bool []
+              (if (= (peek-c) \t)
+                (do (aset pos 0 (+ (aget pos 0) 4)) true)   ;; true
+                (do (aset pos 0 (+ (aget pos 0) 5)) false))) ;; false
+            (parse-null []
+              (aset pos 0 (+ (aget pos 0) 4)) JNULL)        ;; null
+            (parse-num []
+              (let [start (aget pos 0)]
+                (while (and (< (aget pos 0) n)
+                            (let [c (.charAt s (aget pos 0))]
+                              (or (Character/isDigit c)
+                                  (= c \-) (= c \+) (= c \.) (= c \e) (= c \E))))
+                  (aset pos 0 (inc (aget pos 0))))
+                (let [tok (subs s start (aget pos 0))]
+                  (if (or (.contains tok ".") (.contains tok "e") (.contains tok "E"))
+                    (Double/parseDouble tok)
+                    (Long/parseLong tok)))))]
+      (parse-val))))
+
+;; ───────────────────────────────────────────────────────────────────────────
+;; Default corpus path + load
+;; ───────────────────────────────────────────────────────────────────────────
+
+(defn default-test-file
+  "build/test/test.json relative to the repo root.
+   This file lives at test/proto/clojure/provider.clj, so the repo root is
+   three directories up."
+  []
+  (let [here (-> (java.io.File. *file*) .getAbsoluteFile .getParentFile)] ;; test/proto/clojure
+    (-> here .getParentFile .getParentFile .getParentFile               ;; repo root
+        (java.io.File. "build/test/test.json")
+        .getPath)))
+
+;; ───────────────────────────────────────────────────────────────────────────
+;; Group / function classification (mirrors ts isGroupBag / hasGroups)
+;; ───────────────────────────────────────────────────────────────────────────
+
+(defn group-bag?
+  "A group bag is a map with a `set` vector."
+  [v]
+  (and (omap? v) (vector? (get v "set"))))
+
+(defn has-groups?
+  "A function node has at least one child group bag."
+  [v]
+  (and (omap? v)
+       (boolean (some (fn [k] (and (not= k "name") (group-bag? (get v k))))
+                      (okeys v)))))
+
+;; ───────────────────────────────────────────────────────────────────────────
+;; Provider — a plain map {:spec <parsed json>}
+;; ───────────────────────────────────────────────────────────────────────────
+
+(defn load
+  "Parse test.json and return a provider map. Optional explicit path."
+  ([] (load (default-test-file)))
+  ([path] {:spec (json-read (slurp path))}))
+
+(defn raw
+  "The parsed test.json (escape hatch)."
+  [provider]
+  (:spec provider))
+
+(defn- root-node
+  "The struct sub-map if present, else the spec itself."
+  [provider]
+  (let [spec (:spec provider)]
+    (or (and (omap? spec) (get spec "struct")) spec)))
+
+(defn- fn-node
+  [provider fnname]
+  (let [spec (:spec provider)
+        node (or (get (root-node provider) fnname)
+                 (and (omap? spec) (get spec fnname)))]
+    (when (nil? node)
+      (throw (ex-info (str "Unknown function: " fnname) {:fn fnname})))
+    node))
+
+(defn functions
+  "Top-level function names in corpus order."
+  [provider]
+  (let [root (root-node provider)]
+    (vec (filter (fn [k] (or (group-bag? (get root k)) (has-groups? (get root k))))
+                 (okeys root)))))
+
+(defn groups
+  "Group names for a function, in corpus order."
+  [provider fnname]
+  (let [node (fn-node provider fnname)]
+    (vec (filter (fn [k] (and (not= k "name") (group-bag? (get node k))))
+                 (okeys node)))))
+
+;; ───────────────────────────────────────────────────────────────────────────
+;; Normalization
+;; ───────────────────────────────────────────────────────────────────────────
+
+(defn- present?
+  "JSON key presence — true if the map contains the key (value may be JNULL)."
+  [raw key]
+  (and (omap? raw) (contains? raw key)))
+
+(defn- as-string
+  "str of a value that is present and not JNULL, else nil. Mirrors ts
+   `null != raw.id ? String(raw.id) : null` (JSON null counts as absent)."
+  [raw key]
+  (let [v (get raw key)]
+    (when (and (some? v) (not= v JNULL)) (str v))))
+
+(defn resolve-input
+  "Tagged input. Precedence ctx > args > in. For :in, an absent \"in\" key
+   yields JNULL (native null)."
+  [raw]
+  (cond
+    (present? raw "ctx") {:kind :ctx :ctx (get raw "ctx")}
+    (present? raw "args") {:kind :args :args (get raw "args")}
+    :else {:kind :in :in (if (present? raw "in") (get raw "in") JNULL)}))
+
+(defn parse-err
+  "ErrorCheck from an `err` spec.
+   true -> {:any true}; \"/re/\" -> regex; other string -> literal text;
+   anything else -> any error."
+  [err]
+  (cond
+    (true? err) {:any true :text nil :regex false}
+    (string? err)
+    (if-let [m (re-matches #"^/(.+)/$" err)]
+      {:any false :text (second m) :regex true}
+      {:any false :text err :regex false})
+    :else {:any true :text nil :regex false}))
+
+(defn resolve-expect
+  "Tagged expectation. Precedence err > out > match > absent. Uses KEY
+   PRESENCE (contains?), so out:null still yields :value. A co-existing match
+   block is attached as :match on :error / :value."
+  [raw]
+  (let [match-part (when (present? raw "match") (get raw "match"))]
+    (cond
+      (present? raw "err")
+      {:kind :error :error (parse-err (get raw "err")) :match match-part}
+      (present? raw "out")
+      {:kind :value :value (get raw "out") :match match-part}
+      (present? raw "match")
+      {:kind :match :match (get raw "match")}
+      :else {:kind :absent})))
+
+(defn normalize
+  [fnname group index raw]
+  {:function fnname
+   :group group
+   :index index
+   :id (as-string raw "id")
+   :doc (true? (get raw "doc"))
+   :client (as-string raw "client")
+   :input (resolve-input raw)
+   :expect (resolve-expect raw)
+   :raw raw})
+
+(defn entries
+  "All normalized entries for a function (optionally one group)."
+  ([provider fnname] (entries provider fnname nil))
+  ([provider fnname group]
+   (let [node (fn-node provider fnname)
+         gs (if (some? group) [group] (groups provider fnname))]
+     (vec
+      (mapcat
+       (fn [g]
+         (let [bag (get node g)]
+           (when (group-bag? bag)
+             (map-indexed (fn [i e] (normalize fnname g i e)) (get bag "set")))))
+       gs)))))
+
+;; ───────────────────────────────────────────────────────────────────────────
+;; Pure comparison helpers (mirror PROVIDER.md §5)
+;; ───────────────────────────────────────────────────────────────────────────
+
+(declare compact-json)
+
+(defn stringify
+  "The string itself if already a string, else compact JSON."
+  [x]
+  (if (string? x) x (compact-json x)))
+
+(defn- json-escape [^String s]
+  (let [sb (StringBuilder.)]
+    (doseq [c s]
+      (case c
+        \" (.append sb "\\\"")
+        \\ (.append sb "\\\\")
+        \newline (.append sb "\\n")
+        \tab (.append sb "\\t")
+        \return (.append sb "\\r")
+        \backspace (.append sb "\\b")
+        \formfeed (.append sb "\\f")
+        (if (< (int c) 0x20)
+          (.append sb (format "\\u%04x" (int c)))
+          (.append sb c))))
+    (.toString sb)))
+
+(defn- num->json [x]
+  ;; Render Doubles with integral value as 1, not 1.0, to match JSON.stringify.
+  (if (and (instance? Double x) (== x (Math/rint x)) (Double/isFinite x))
+    (str (long x))
+    (str x)))
+
+(defn compact-json
+  "Compact JSON serialization mirroring JSON.stringify for our data model."
+  [x]
+  (cond
+    (or (nil? x) (= x JNULL)) "null"
+    (string? x) (str "\"" (json-escape x) "\"")
+    (boolean? x) (str x)
+    (number? x) (num->json x)
+    (vector? x) (str "[" (str/join "," (map compact-json x)) "]")
+    (sequential? x) (str "[" (str/join "," (map compact-json x)) "]")
+    (map? x) (str "{"
+                  (str/join ","
+                            (map (fn [k] (str "\"" (json-escape (str k)) "\":"
+                                              (compact-json (get x k))))
+                                 (okeys x)))
+                  "}")
+    :else (str "\"" (json-escape (str x)) "\"")))
+
+(defn- norm-null
+  "Normalize __NULL__, JNULL and nil all to nil (lenient null collapse)."
+  [x]
+  (cond
+    (or (= x NULLMARK) (= x JNULL) (nil? x)) nil
+    (vector? x) (mapv norm-null x)
+    (sequential? x) (mapv norm-null x)
+    (map? x) (reduce (fn [acc k] (assoc acc k (norm-null (get x k)))) {} (keys x))
+    :else x))
+
+(defn- norm-mark
+  "Strict normalize — only __NULL__ collapses to nil; JNULL stays distinct."
+  [x]
+  (cond
+    (= x NULLMARK) nil
+    (vector? x) (mapv norm-mark x)
+    (sequential? x) (mapv norm-mark x)
+    (map? x) (reduce (fn [acc k] (assoc acc k (norm-mark (get x k)))) {} (keys x))
+    :else x))
+
+(defn- deep-eq
+  "Deep equality with JS-=== semantics: booleans never equal numbers, arrays
+   only equal arrays, maps only equal maps (by key set + values)."
+  [a b]
+  (cond
+    ;; bool/number distinction (Clojure already keeps true ≠ 1, but be explicit)
+    (not= (boolean? a) (boolean? b)) false
+    (and (sequential? a) (sequential? b))
+    (and (= (count a) (count b))
+         (every? true? (map deep-eq a b)))
+    (or (sequential? a) (sequential? b)) false
+    (and (map? a) (map? b))
+    (let [ak (keys a) bk (keys b)]
+      (and (= (count ak) (count bk))
+           (every? (fn [k] (and (contains? b k) (deep-eq (get a k) (get b k)))) ak)))
+    (or (map? a) (map? b)) false
+    :else (= a b)))
+
+(defn matchval
+  "Scalar primitive match. check === base; else if check is a string:
+   \"/re/\" => regex test of stringify(base); else case-insensitive substring
+   of stringify(base). A function check => true."
+  [check base]
+  (cond
+    (deep-eq check base) true
+    (string? check)
+    (let [basestr (stringify base)]
+      (if-let [m (re-matches #"^/(.+)/$" check)]
+        (boolean (re-find (Pattern/compile (second m)) basestr))
+        (str/includes? (str/lower-case basestr) (str/lower-case check))))
+    (fn? check) true
+    :else false))
+
+(defn equal
+  "Deep equality with lenient null collapse (runner default null:true)."
+  [expected actual]
+  (deep-eq (norm-null expected) (norm-null actual)))
+
+(defn equal-strict
+  "Deep equality where absent/JNULL is distinct from __NULL__ (null:false)."
+  [expected actual]
+  (deep-eq (norm-mark expected) (norm-mark actual)))
+
+(defn error-matches
+  "ErrorCheck vs a thrown message."
+  [check message]
+  (cond
+    (:any check) true
+    (nil? (:text check)) false
+    (:regex check) (boolean (re-find (Pattern/compile (:text check)) message))
+    :else (str/includes? (str/lower-case message) (str/lower-case (:text check)))))
+
+;; getpath for struct-match — returns MISSING for absent, distinct from JNULL.
+(defn- mt-getpath [store path]
+  (loop [cur store
+         ks path]
+    (if (empty? ks)
+      cur
+      (let [k (first ks)]
+        (cond
+          (or (nil? cur) (= cur MISSING) (= cur JNULL)) MISSING
+          (vector? cur)
+          (let [idx (try (Integer/parseInt (str k)) (catch Exception _ -1))]
+            (recur (if (and (<= 0 idx) (< idx (count cur))) (nth cur idx) MISSING)
+                   (rest ks)))
+          (map? cur)
+          (recur (if (contains? cur (str k)) (get cur (str k)) MISSING) (rest ks))
+          :else MISSING)))))
+
+(defn- walk-leaves [node path f]
+  (cond
+    (vector? node)
+    (doseq [[i v] (map-indexed vector node)]
+      (walk-leaves v (conj path (str i)) f))
+    (and (sequential? node) (not (string? node)))
+    (doseq [[i v] (map-indexed vector node)]
+      (walk-leaves v (conj path (str i)) f))
+    (map? node)
+    (doseq [k (okeys node)]
+      (walk-leaves (get node k) (conj path k) f))
+    :else (f node path)))
+
+(defn struct-match
+  "Partial structural match: every leaf of `check` must match `base` at its
+   path. Returns {:ok true} or {:ok false :path .. :expected .. :actual ..}."
+  [check base]
+  (let [result (atom {:ok true})]
+    (walk-leaves
+     check []
+     (fn [val path]
+       (when (:ok @result)
+         (let [baseval (mt-getpath base path)
+               present (not= baseval MISSING)
+               cmp (if present baseval nil)]
+           (cond
+             (and present (deep-eq baseval val)) nil
+             (and (= val UNDEFMARK) (not present)) nil
+             (and (= val EXISTSMARK) present (not= baseval JNULL) (some? baseval)) nil
+             (not (matchval val cmp))
+             (reset! result {:ok false :path path :expected val :actual cmp}))))))
+    @result))
diff --git a/test/proto/clojure/smoke.clj b/test/proto/clojure/smoke.clj
new file mode 100644
index 0000000..50a4fbc
--- /dev/null
+++ b/test/proto/clojure/smoke.clj
@@ -0,0 +1,64 @@
+;; Smoke test for the Clojure test provider port. Prints summary stats that
+;; must match the canonical TS output documented in PROVIDER work.
+;;
+;; Run (once a Clojure toolchain is available), from this directory:
+;;   clojure -M smoke.clj
+;; or with the file on the classpath:
+;;   clojure -M -m voxgig.proto.smoke
+
+(ns voxgig.proto.smoke
+  (:require [voxgig.proto.provider :as p]
+            [clojure.string :as str]))
+
+(defn- fmt-value
+  "Render an expectation value for display: JNULL -> null, strings bare,
+   everything else via compact JSON."
+  [v]
+  (cond
+    (= v p/JNULL) "null"
+    (string? v) v
+    :else (p/compact-json v)))
+
+(defn run []
+  (let [prov (p/load)
+        fns (p/functions prov)]
+    (println (str "functions: " (str/join ", " fns)))
+
+    (let [all (mapcat (fn [fnname] (p/entries prov fnname)) fns)
+          total (count all)
+          expect-kinds (reduce (fn [acc e]
+                                 (update acc (name (get-in e [:expect :kind])) (fnil inc 0)))
+                               {} all)
+          input-kinds (reduce (fn [acc e]
+                                (update acc (name (get-in e [:input :kind])) (fnil inc 0)))
+                              {} all)]
+      (println (str "total entries: " total))
+      (println (str "expect kinds: "
+                    (str/join ", " (map (fn [k] (str k "=" (get expect-kinds k)))
+                                        (sort (keys expect-kinds))))))
+      (println (str "input kinds: "
+                    (str/join ", " (map (fn [k] (str k "=" (get input-kinds k)))
+                                        (sort (keys input-kinds)))))))
+
+    (let [e (first (p/entries prov "getpath" "basic"))]
+      (println (str "getpath/basic[0]: "
+                    "id=" (:id e)
+                    ", doc=" (:doc e)
+                    ", input.kind=" (name (get-in e [:input :kind]))
+                    ", expect.kind=" (name (get-in e [:expect :kind]))
+                    ", expect.value=" (fmt-value (get-in e [:expect :value])))))
+
+    ;; ─── helper sanity checks ──────────────────────────────────────────────
+    (println (str "equal(null, absent) lenient: "
+                  (p/equal p/JNULL nil)))
+    (println (str "equal-strict distinguishes null vs __NULL__-collapse: "
+                  (p/equal-strict nil "__NULL__") " / " (p/equal-strict nil 1)))
+    (println (str "error-matches substring case-insensitive: "
+                  (p/error-matches {:any false :text "Foo" :regex false} "a foobar error")))
+    (println (str "struct-match failure: "
+                  (p/struct-match {"a" {"b" 2}} {"a" {"b" 3}})))))
+
+(defn -main [& _] (run))
+
+;; Allow `clojure -M smoke.clj` (script style) to execute directly.
+(run)
diff --git a/test/proto/cpp/provider.hpp b/test/proto/cpp/provider.hpp
new file mode 100644
index 0000000..1ebc13d
--- /dev/null
+++ b/test/proto/cpp/provider.hpp
@@ -0,0 +1,920 @@
+// Test Provider (prototype) — C++17 port.
+//
+// Reads the shared corpus (build/test/test.json) and hands test code clean,
+// normalized cases. It is NOT a test runner: it never calls the subject and
+// never asserts. See ../PROVIDER.md for the model and ../ts/provider.ts for
+// the canonical reference this is ported from.
+//
+// Self-contained and dependency-free: includes its own minimal JSON parser and
+// does NOT depend on the cpp port's value.hpp. Standard library only.
+
+#ifndef VOXGIG_TEST_PROVIDER_HPP
+#define VOXGIG_TEST_PROVIDER_HPP
+
+#include <cctype>
+#include <cstdint>
+#include <cstdlib>
+#include <fstream>
+#include <memory>
+#include <optional>
+#include <regex>
+#include <sstream>
+#include <stdexcept>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace voxgig {
+namespace testproto {
+
+// ─── JSON value type ───────────────────────────────────────────────────────
+// Order-preserving object: vector<pair<string,Value>> (NOT std::map) so that
+// functions()/groups() keep corpus order.
+
+class Value;
+using Array = std::vector<Value>;
+using Object = std::vector<std::pair<std::string, Value>>;
+
+enum class Type { Null, Bool, Number, String, Array, Object };
+
+class Value {
+ public:
+  Type type = Type::Null;
+  bool b = false;
+  double num = 0.0;
+  std::string str;
+  std::shared_ptr<Array> arr;
+  std::shared_ptr<Object> obj;
+
+  Value() : type(Type::Null) {}
+  static Value null() { return Value(); }
+  static Value boolean(bool v) {
+    Value x;
+    x.type = Type::Bool;
+    x.b = v;
+    return x;
+  }
+  static Value number(double v) {
+    Value x;
+    x.type = Type::Number;
+    x.num = v;
+    return x;
+  }
+  static Value string(std::string v) {
+    Value x;
+    x.type = Type::String;
+    x.str = std::move(v);
+    return x;
+  }
+  static Value array() {
+    Value x;
+    x.type = Type::Array;
+    x.arr = std::make_shared<Array>();
+    return x;
+  }
+  static Value object() {
+    Value x;
+    x.type = Type::Object;
+    x.obj = std::make_shared<Object>();
+    return x;
+  }
+
+  bool is_null() const { return type == Type::Null; }
+  bool is_bool() const { return type == Type::Bool; }
+  bool is_number() const { return type == Type::Number; }
+  bool is_string() const { return type == Type::String; }
+  bool is_array() const { return type == Type::Array; }
+  bool is_object() const { return type == Type::Object; }
+
+  // Object helpers (order-preserving).
+  bool has(const std::string& key) const {
+    if (!is_object()) return false;
+    for (const auto& kv : *obj)
+      if (kv.first == key) return true;
+    return false;
+  }
+  // Returns nullptr if absent.
+  const Value* find(const std::string& key) const {
+    if (!is_object()) return nullptr;
+    for (const auto& kv : *obj)
+      if (kv.first == key) return &kv.second;
+    return nullptr;
+  }
+  void set(const std::string& key, Value v) {
+    if (!is_object()) {
+      type = Type::Object;
+      obj = std::make_shared<Object>();
+    }
+    for (auto& kv : *obj) {
+      if (kv.first == key) {
+        kv.second = std::move(v);
+        return;
+      }
+    }
+    obj->emplace_back(key, std::move(v));
+  }
+  void push(Value v) {
+    if (!is_array()) {
+      type = Type::Array;
+      arr = std::make_shared<Array>();
+    }
+    arr->push_back(std::move(v));
+  }
+};
+
+// ─── compact JSON serialization ────────────────────────────────────────────
+
+inline void jsonEscape(const std::string& s, std::string& out) {
+  out.push_back('"');
+  for (unsigned char c : s) {
+    switch (c) {
+      case '"':
+        out += "\\\"";
+        break;
+      case '\\':
+        out += "\\\\";
+        break;
+      case '\b':
+        out += "\\b";
+        break;
+      case '\f':
+        out += "\\f";
+        break;
+      case '\n':
+        out += "\\n";
+        break;
+      case '\r':
+        out += "\\r";
+        break;
+      case '\t':
+        out += "\\t";
+        break;
+      default:
+        if (c < 0x20) {
+          static const char* hex = "0123456789abcdef";
+          out += "\\u00";
+          out.push_back(hex[(c >> 4) & 0xF]);
+          out.push_back(hex[c & 0xF]);
+        } else {
+          out.push_back(static_cast<char>(c));
+        }
+    }
+  }
+  out.push_back('"');
+}
+
+inline std::string numToString(double d) {
+  // Integer-valued doubles render without a decimal point (matches JSON.stringify
+  // for whole numbers), else a round-trippable representation.
+  if (d == static_cast<int64_t>(d) && d >= -9.007199254740992e15 &&
+      d <= 9.007199254740992e15) {
+    std::ostringstream oss;
+    oss << static_cast<int64_t>(d);
+    return oss.str();
+  }
+  std::ostringstream oss;
+  oss.precision(17);
+  oss << d;
+  return oss.str();
+}
+
+inline void jsonify(const Value& v, std::string& out) {
+  switch (v.type) {
+    case Type::Null:
+      out += "null";
+      break;
+    case Type::Bool:
+      out += v.b ? "true" : "false";
+      break;
+    case Type::Number:
+      out += numToString(v.num);
+      break;
+    case Type::String:
+      jsonEscape(v.str, out);
+      break;
+    case Type::Array: {
+      out.push_back('[');
+      bool first = true;
+      for (const auto& e : *v.arr) {
+        if (!first) out.push_back(',');
+        first = false;
+        jsonify(e, out);
+      }
+      out.push_back(']');
+      break;
+    }
+    case Type::Object: {
+      out.push_back('{');
+      bool first = true;
+      for (const auto& kv : *v.obj) {
+        if (!first) out.push_back(',');
+        first = false;
+        jsonEscape(kv.first, out);
+        out.push_back(':');
+        jsonify(kv.second, out);
+      }
+      out.push_back('}');
+      break;
+    }
+  }
+}
+
+inline std::string jsonify(const Value& v) {
+  std::string out;
+  jsonify(v, out);
+  return out;
+}
+
+// ─── recursive-descent JSON parser ─────────────────────────────────────────
+
+class JsonParser {
+ public:
+  explicit JsonParser(const std::string& s) : s_(s), n_(s.size()) {}
+
+  Value parse() {
+    skipWs();
+    Value v = parseValue();
+    skipWs();
+    if (i_ != n_) fail("trailing characters");
+    return v;
+  }
+
+ private:
+  const std::string& s_;
+  size_t i_ = 0;
+  size_t n_;
+
+  [[noreturn]] void fail(const std::string& msg) {
+    std::ostringstream oss;
+    oss << "JSON parse error at offset " << i_ << ": " << msg;
+    throw std::runtime_error(oss.str());
+  }
+
+  char peek() { return i_ < n_ ? s_[i_] : '\0'; }
+  char get() { return i_ < n_ ? s_[i_++] : '\0'; }
+
+  void skipWs() {
+    while (i_ < n_) {
+      char c = s_[i_];
+      if (c == ' ' || c == '\t' || c == '\n' || c == '\r')
+        i_++;
+      else
+        break;
+    }
+  }
+
+  Value parseValue() {
+    skipWs();
+    char c = peek();
+    switch (c) {
+      case '{':
+        return parseObject();
+      case '[':
+        return parseArray();
+      case '"':
+        return Value::string(parseString());
+      case 't':
+      case 'f':
+        return parseBool();
+      case 'n':
+        return parseNull();
+      default:
+        if (c == '-' || (c >= '0' && c <= '9')) return parseNumber();
+        fail("unexpected character");
+    }
+  }
+
+  Value parseObject() {
+    get();  // {
+    Value v = Value::object();
+    skipWs();
+    if (peek() == '}') {
+      get();
+      return v;
+    }
+    while (true) {
+      skipWs();
+      if (peek() != '"') fail("expected string key");
+      std::string key = parseString();
+      skipWs();
+      if (get() != ':') fail("expected ':'");
+      Value val = parseValue();
+      v.obj->emplace_back(std::move(key), std::move(val));
+      skipWs();
+      char c = get();
+      if (c == ',') continue;
+      if (c == '}') break;
+      fail("expected ',' or '}'");
+    }
+    return v;
+  }
+
+  Value parseArray() {
+    get();  // [
+    Value v = Value::array();
+    skipWs();
+    if (peek() == ']') {
+      get();
+      return v;
+    }
+    while (true) {
+      Value el = parseValue();
+      v.arr->push_back(std::move(el));
+      skipWs();
+      char c = get();
+      if (c == ',') continue;
+      if (c == ']') break;
+      fail("expected ',' or ']'");
+    }
+    return v;
+  }
+
+  void appendUtf8(uint32_t cp, std::string& out) {
+    if (cp <= 0x7F) {
+      out.push_back(static_cast<char>(cp));
+    } else if (cp <= 0x7FF) {
+      out.push_back(static_cast<char>(0xC0 | (cp >> 6)));
+      out.push_back(static_cast<char>(0x80 | (cp & 0x3F)));
+    } else if (cp <= 0xFFFF) {
+      out.push_back(static_cast<char>(0xE0 | (cp >> 12)));
+      out.push_back(static_cast<char>(0x80 | ((cp >> 6) & 0x3F)));
+      out.push_back(static_cast<char>(0x80 | (cp & 0x3F)));
+    } else {
+      out.push_back(static_cast<char>(0xF0 | (cp >> 18)));
+      out.push_back(static_cast<char>(0x80 | ((cp >> 12) & 0x3F)));
+      out.push_back(static_cast<char>(0x80 | ((cp >> 6) & 0x3F)));
+      out.push_back(static_cast<char>(0x80 | (cp & 0x3F)));
+    }
+  }
+
+  uint32_t parseHex4() {
+    uint32_t v = 0;
+    for (int k = 0; k < 4; k++) {
+      char c = get();
+      v <<= 4;
+      if (c >= '0' && c <= '9')
+        v |= static_cast<uint32_t>(c - '0');
+      else if (c >= 'a' && c <= 'f')
+        v |= static_cast<uint32_t>(c - 'a' + 10);
+      else if (c >= 'A' && c <= 'F')
+        v |= static_cast<uint32_t>(c - 'A' + 10);
+      else
+        fail("invalid \\u escape");
+    }
+    return v;
+  }
+
+  std::string parseString() {
+    get();  // opening "
+    std::string out;
+    while (true) {
+      if (i_ >= n_) fail("unterminated string");
+      char c = get();
+      if (c == '"') break;
+      if (c == '\\') {
+        char e = get();
+        switch (e) {
+          case '"':
+            out.push_back('"');
+            break;
+          case '\\':
+            out.push_back('\\');
+            break;
+          case '/':
+            out.push_back('/');
+            break;
+          case 'b':
+            out.push_back('\b');
+            break;
+          case 'f':
+            out.push_back('\f');
+            break;
+          case 'n':
+            out.push_back('\n');
+            break;
+          case 'r':
+            out.push_back('\r');
+            break;
+          case 't':
+            out.push_back('\t');
+            break;
+          case 'u': {
+            uint32_t cp = parseHex4();
+            if (cp >= 0xD800 && cp <= 0xDBFF) {
+              // high surrogate; expect a low surrogate next
+              if (peek() == '\\') {
+                get();
+                if (get() != 'u') fail("expected low surrogate");
+                uint32_t lo = parseHex4();
+                if (lo >= 0xDC00 && lo <= 0xDFFF) {
+                  cp = 0x10000 + ((cp - 0xD800) << 10) + (lo - 0xDC00);
+                } else {
+                  // unpaired; emit both as-is
+                  appendUtf8(cp, out);
+                  cp = lo;
+                }
+              }
+            }
+            appendUtf8(cp, out);
+            break;
+          }
+          default:
+            fail("invalid escape");
+        }
+      } else {
+        out.push_back(c);
+      }
+    }
+    return out;
+  }
+
+  Value parseNumber() {
+    size_t start = i_;
+    if (peek() == '-') get();
+    while (i_ < n_ && s_[i_] >= '0' && s_[i_] <= '9') i_++;
+    if (peek() == '.') {
+      get();
+      while (i_ < n_ && s_[i_] >= '0' && s_[i_] <= '9') i_++;
+    }
+    if (peek() == 'e' || peek() == 'E') {
+      get();
+      if (peek() == '+' || peek() == '-') get();
+      while (i_ < n_ && s_[i_] >= '0' && s_[i_] <= '9') i_++;
+    }
+    std::string tok = s_.substr(start, i_ - start);
+    return Value::number(std::stod(tok));
+  }
+
+  Value parseBool() {
+    if (s_.compare(i_, 4, "true") == 0) {
+      i_ += 4;
+      return Value::boolean(true);
+    }
+    if (s_.compare(i_, 5, "false") == 0) {
+      i_ += 5;
+      return Value::boolean(false);
+    }
+    fail("invalid literal");
+  }
+
+  Value parseNull() {
+    if (s_.compare(i_, 4, "null") == 0) {
+      i_ += 4;
+      return Value::null();
+    }
+    fail("invalid literal");
+  }
+};
+
+inline Value parseJson(const std::string& text) {
+  JsonParser p(text);
+  return p.parse();
+}
+
+// ─── normalized model ──────────────────────────────────────────────────────
+
+enum class InputKind { IN, ARGS, CTX };
+enum class ExpectKind { VALUE, ERROR, MATCH, ABSENT };
+
+struct Input {
+  InputKind kind = InputKind::IN;
+  Value in;    // kind==IN
+  Value args;  // kind==ARGS
+  Value ctx;   // kind==CTX
+};
+
+struct ErrorCheck {
+  bool any = false;
+  std::optional<std::string> text;
+  bool regex = false;
+};
+
+struct Expect {
+  ExpectKind kind = ExpectKind::ABSENT;
+  std::optional<Value> value;
+  std::optional<ErrorCheck> error;
+  std::optional<Value> match;
+};
+
+struct Entry {
+  std::string function;
+  std::string group;
+  size_t index = 0;
+  std::optional<std::string> id;
+  bool doc = false;
+  std::optional<std::string> client;
+  Input input;
+  Expect expect;
+  Value raw;
+};
+
+struct MatchResult {
+  bool ok = true;
+  std::vector<std::string> path;
+  std::optional<Value> expected;
+  std::optional<Value> actual;
+};
+
+// ─── markers ───────────────────────────────────────────────────────────────
+
+inline const std::string& NULLMARK() {
+  static const std::string s = "__NULL__";
+  return s;
+}
+inline const std::string& UNDEFMARK() {
+  static const std::string s = "__UNDEF__";
+  return s;
+}
+inline const std::string& EXISTSMARK() {
+  static const std::string s = "__EXISTS__";
+  return s;
+}
+
+// ─── group / function detection ────────────────────────────────────────────
+
+// A group bag is a map with a `set` array.
+inline bool isGroupBag(const Value& v) {
+  if (!v.is_object()) return false;
+  const Value* set = v.find("set");
+  return set != nullptr && set->is_array();
+}
+
+// A function node has at least one child group bag (excluding "name").
+inline bool hasGroups(const Value& v) {
+  if (!v.is_object()) return false;
+  for (const auto& kv : *v.obj) {
+    if (kv.first != "name" && isGroupBag(kv.second)) return true;
+  }
+  return false;
+}
+
+// ─── stringify (for match helpers) ─────────────────────────────────────────
+
+inline std::string stringify(const Value& x) {
+  if (x.is_string()) return x.str;
+  return jsonify(x);
+}
+
+// ─── null normalization (equal / equalStrict) ──────────────────────────────
+
+// normNull: __NULL__ -> null and recurse. (Absent maps to null at the source;
+// here all explicit values are present, so we only collapse the marker.)
+inline Value normNull(const Value& x) {
+  if (x.is_string() && x.str == NULLMARK()) return Value::null();
+  if (x.is_array()) {
+    Value out = Value::array();
+    for (const auto& e : *x.arr) out.arr->push_back(normNull(e));
+    return out;
+  }
+  if (x.is_object()) {
+    Value out = Value::object();
+    for (const auto& kv : *x.obj) out.obj->emplace_back(kv.first, normNull(kv.second));
+    return out;
+  }
+  return x;
+}
+
+inline Value normMark(const Value& x) { return normNull(x); }
+
+inline bool scalarEq(const Value& a, const Value& b) {
+  if (a.type != b.type) return false;
+  switch (a.type) {
+    case Type::Null:
+      return true;
+    case Type::Bool:
+      return a.b == b.b;
+    case Type::Number:
+      return a.num == b.num;
+    case Type::String:
+      return a.str == b.str;
+    default:
+      return false;
+  }
+}
+
+inline bool deepEq(const Value& a, const Value& b) {
+  if (a.is_array() && b.is_array()) {
+    if (a.arr->size() != b.arr->size()) return false;
+    for (size_t i = 0; i < a.arr->size(); i++)
+      if (!deepEq((*a.arr)[i], (*b.arr)[i])) return false;
+    return true;
+  }
+  if (a.is_object() && b.is_object()) {
+    if (a.obj->size() != b.obj->size()) return false;
+    // Mirrors JS deepEq: same number of keys, every key in `a` present in `b`
+    // with deep-equal value (key order not required).
+    for (const auto& kv : *a.obj) {
+      const Value* bv = b.find(kv.first);
+      if (bv == nullptr || !deepEq(kv.second, *bv)) return false;
+    }
+    return true;
+  }
+  return scalarEq(a, b);
+}
+
+// ─── pure comparison helpers ───────────────────────────────────────────────
+
+inline bool matchval(const Value& check, const Value& base) {
+  if (scalarEq(check, base)) return true;
+  // Deep equality for compound values (=== in JS is identity, but a string
+  // check against a compound base never matches by identity; preserve the
+  // string-special-casing below for strings).
+  if (check.is_string()) {
+    std::string basestr = stringify(base);
+    const std::string& c = check.str;
+    if (c.size() >= 2 && c.front() == '/' && c.back() == '/') {
+      std::string re = c.substr(1, c.size() - 2);
+      try {
+        std::regex rx(re);
+        return std::regex_search(basestr, rx);
+      } catch (const std::regex_error&) {
+        return false;
+      }
+    }
+    std::string lo_base = basestr, lo_c = c;
+    for (auto& ch : lo_base) ch = static_cast<char>(std::tolower(static_cast<unsigned char>(ch)));
+    for (auto& ch : lo_c) ch = static_cast<char>(std::tolower(static_cast<unsigned char>(ch)));
+    return lo_base.find(lo_c) != std::string::npos;
+  }
+  // No function type in this value model; otherwise would return true.
+  return false;
+}
+
+inline bool equal(const Value& expected, const Value& actual) {
+  return deepEq(normNull(expected), normNull(actual));
+}
+
+inline bool equalStrict(const Value& expected, const Value& actual) {
+  return deepEq(normMark(expected), normMark(actual));
+}
+
+inline bool errorMatches(const ErrorCheck& check, const std::string& message) {
+  if (check.any) return true;
+  if (!check.text.has_value()) return false;
+  if (check.regex) {
+    try {
+      std::regex rx(*check.text);
+      return std::regex_search(message, rx);
+    } catch (const std::regex_error&) {
+      return false;
+    }
+  }
+  std::string lo_msg = message, lo_t = *check.text;
+  for (auto& c : lo_msg) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+  for (auto& c : lo_t) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+  return lo_msg.find(lo_t) != std::string::npos;
+}
+
+// getpath used by structMatch: returns nullptr for an absent (undefined) slot.
+inline const Value* getpathp(const Value* store, const std::vector<std::string>& path) {
+  const Value* cur = store;
+  for (const auto& key : path) {
+    if (cur == nullptr || cur->is_null()) return nullptr;
+    if (cur->is_array()) {
+      // numeric index
+      char* end = nullptr;
+      long idx = std::strtol(key.c_str(), &end, 10);
+      if (end == key.c_str() || *end != '\0' || idx < 0 ||
+          static_cast<size_t>(idx) >= cur->arr->size()) {
+        cur = nullptr;
+      } else {
+        cur = &(*cur->arr)[static_cast<size_t>(idx)];
+      }
+    } else if (cur->is_object()) {
+      cur = cur->find(key);
+    } else {
+      cur = nullptr;
+    }
+  }
+  return cur;
+}
+
+inline bool isNodeV(const Value& v) { return v.is_array() || v.is_object(); }
+
+// walkLeaves: visit every scalar leaf of `node` with its path.
+template <typename Fn>
+inline void walkLeaves(const Value& node, std::vector<std::string>& path, Fn&& fn) {
+  if (node.is_array()) {
+    for (size_t i = 0; i < node.arr->size(); i++) {
+      path.push_back(std::to_string(i));
+      walkLeaves((*node.arr)[i], path, fn);
+      path.pop_back();
+    }
+  } else if (node.is_object()) {
+    for (const auto& kv : *node.obj) {
+      path.push_back(kv.first);
+      walkLeaves(kv.second, path, fn);
+      path.pop_back();
+    }
+  } else {
+    fn(node, path);
+  }
+}
+
+inline MatchResult structMatch(const Value& check, const Value& base) {
+  MatchResult result;
+  result.ok = true;
+  std::vector<std::string> path;
+  walkLeaves(check, path, [&](const Value& val, const std::vector<std::string>& p) {
+    if (!result.ok) return;
+    const Value* basevalp = getpathp(&base, p);
+    Value baseval = basevalp ? *basevalp : Value::null();
+    bool absent = (basevalp == nullptr);
+    if (!absent && scalarEq(val, baseval)) return;
+    if (val.is_string() && val.str == UNDEFMARK() && absent) return;
+    if (val.is_string() && val.str == EXISTSMARK() && !absent && !baseval.is_null()) return;
+    if (!matchval(val, baseval)) {
+      result.ok = false;
+      result.path = p;
+      result.expected = val;
+      result.actual = basevalp ? std::optional<Value>(*basevalp) : std::nullopt;
+    }
+  });
+  return result;
+}
+
+// ─── normalization (raw -> Entry) ──────────────────────────────────────────
+
+inline Input resolveInput(const Value& raw) {
+  Input in;
+  if (raw.has("ctx")) {
+    in.kind = InputKind::CTX;
+    in.ctx = *raw.find("ctx");
+    return in;
+  }
+  if (raw.has("args")) {
+    in.kind = InputKind::ARGS;
+    in.args = *raw.find("args");
+    return in;
+  }
+  in.kind = InputKind::IN;
+  const Value* p = raw.find("in");
+  in.in = p ? *p : Value::null();
+  return in;
+}
+
+inline ErrorCheck parseErr(const Value& err) {
+  ErrorCheck ec;
+  if (err.is_bool() && err.b) {
+    ec.any = true;
+    return ec;
+  }
+  if (err.is_string()) {
+    const std::string& s = err.str;
+    if (s.size() >= 2 && s.front() == '/' && s.back() == '/') {
+      ec.any = false;
+      ec.text = s.substr(1, s.size() - 2);
+      ec.regex = true;
+      return ec;
+    }
+    ec.any = false;
+    ec.text = s;
+    ec.regex = false;
+    return ec;
+  }
+  // Non-true, non-string err spec: treat as "any error".
+  ec.any = true;
+  return ec;
+}
+
+inline Expect resolveExpect(const Value& raw) {
+  Expect e;
+  std::optional<Value> matchPart;
+  if (raw.has("match")) matchPart = *raw.find("match");
+
+  if (raw.has("err")) {
+    e.kind = ExpectKind::ERROR;
+    e.error = parseErr(*raw.find("err"));
+    e.match = matchPart;
+    return e;
+  }
+  if (raw.has("out")) {
+    e.kind = ExpectKind::VALUE;
+    e.value = *raw.find("out");
+    e.match = matchPart;
+    return e;
+  }
+  if (raw.has("match")) {
+    e.kind = ExpectKind::MATCH;
+    e.match = *raw.find("match");
+    return e;
+  }
+  e.kind = ExpectKind::ABSENT;
+  return e;
+}
+
+inline Entry normalize(const std::string& fn, const std::string& group, size_t index,
+                       const Value& raw) {
+  Entry e;
+  e.function = fn;
+  e.group = group;
+  e.index = index;
+  const Value* idp = raw.find("id");
+  if (idp != nullptr && !idp->is_null()) {
+    e.id = idp->is_string() ? idp->str : stringify(*idp);
+  }
+  const Value* docp = raw.find("doc");
+  e.doc = (docp != nullptr && docp->is_bool() && docp->b);
+  const Value* clientp = raw.find("client");
+  if (clientp != nullptr && !clientp->is_null()) {
+    e.client = clientp->is_string() ? clientp->str : stringify(*clientp);
+  }
+  e.input = resolveInput(raw);
+  e.expect = resolveExpect(raw);
+  e.raw = raw;
+  return e;
+}
+
+// ─── default corpus path resolution ────────────────────────────────────────
+
+// Convention: when no explicit path is given, resolve "build/test/test.json"
+// relative to the current working directory (the repo root). The smoke harness
+// is run from the repo root, matching the existing cpp runner which reads
+// "../build/test/test.json" from its own build dir. Tests may pass an explicit
+// path.
+inline std::string defaultTestFile() { return "build/test/test.json"; }
+
+// ─── TestProvider ──────────────────────────────────────────────────────────
+
+class TestProvider {
+ public:
+  Value spec;
+
+  TestProvider() = default;
+  explicit TestProvider(Value s) : spec(std::move(s)) {}
+
+  static TestProvider load(const std::string& path = "") {
+    std::string file = path.empty() ? defaultTestFile() : path;
+    std::ifstream f(file, std::ios::binary);
+    if (!f) throw std::runtime_error("cannot open corpus: " + file);
+    std::ostringstream ss;
+    ss << f.rdbuf();
+    return TestProvider(parseJson(ss.str()));
+  }
+
+  const Value& raw() const { return spec; }
+
+  std::vector<std::string> functions() const {
+    const Value& root = rootNode();
+    std::vector<std::string> out;
+    if (!root.is_object()) return out;
+    for (const auto& kv : *root.obj) {
+      if (isGroupBag(kv.second) || hasGroups(kv.second)) out.push_back(kv.first);
+    }
+    return out;
+  }
+
+  std::vector<std::string> groups(const std::string& fn) const {
+    const Value& node = fnNode(fn);
+    std::vector<std::string> out;
+    if (!node.is_object()) return out;
+    for (const auto& kv : *node.obj) {
+      if (kv.first != "name" && isGroupBag(kv.second)) out.push_back(kv.first);
+    }
+    return out;
+  }
+
+  std::vector<Entry> entries(const std::string& fn,
+                             const std::optional<std::string>& group = std::nullopt) const {
+    const Value& node = fnNode(fn);
+    std::vector<std::string> gs;
+    if (group.has_value())
+      gs.push_back(*group);
+    else
+      gs = groups(fn);
+
+    std::vector<Entry> out;
+    for (const auto& g : gs) {
+      const Value* bag = node.find(g);
+      if (bag == nullptr || !isGroupBag(*bag)) continue;
+      const Value* set = bag->find("set");
+      if (set == nullptr || !set->is_array()) continue;
+      for (size_t i = 0; i < set->arr->size(); i++) {
+        out.push_back(normalize(fn, g, i, (*set->arr)[i]));
+      }
+    }
+    return out;
+  }
+
+ private:
+  const Value& rootNode() const {
+    const Value* s = spec.find("struct");
+    return (s != nullptr) ? *s : spec;
+  }
+
+  const Value& fnNode(const std::string& fn) const {
+    const Value* s = spec.find("struct");
+    if (s != nullptr) {
+      const Value* node = s->find(fn);
+      if (node != nullptr) return *node;
+    }
+    const Value* node = spec.find(fn);
+    if (node != nullptr) return *node;
+    throw std::runtime_error("Unknown function: " + fn);
+  }
+};
+
+}  // namespace testproto
+}  // namespace voxgig
+
+#endif  // VOXGIG_TEST_PROVIDER_HPP
diff --git a/test/proto/cpp/smoke.cpp b/test/proto/cpp/smoke.cpp
new file mode 100644
index 0000000..3227e97
--- /dev/null
+++ b/test/proto/cpp/smoke.cpp
@@ -0,0 +1,114 @@
+// Smoke test for the C++ test-provider port.
+//
+// Loads build/test/test.json (resolved relative to CWD; run from repo root),
+// prints the functions list, total entries, expect-kind counts, input-kind
+// counts, and the first getpath/basic entry.
+//
+//   g++ -std=c++17 -O2 test/proto/cpp/smoke.cpp -o /tmp/cpp_smoke
+//   (cd /home/user/struct && /tmp/cpp_smoke)
+
+#include <iostream>
+#include <string>
+
+#include "provider.hpp"
+
+using namespace voxgig::testproto;
+
+static std::string expectKindName(ExpectKind k) {
+  switch (k) {
+    case ExpectKind::VALUE:
+      return "value";
+    case ExpectKind::ERROR:
+      return "error";
+    case ExpectKind::MATCH:
+      return "match";
+    case ExpectKind::ABSENT:
+      return "absent";
+  }
+  return "?";
+}
+
+static std::string inputKindName(InputKind k) {
+  switch (k) {
+    case InputKind::IN:
+      return "in";
+    case InputKind::ARGS:
+      return "args";
+    case InputKind::CTX:
+      return "ctx";
+  }
+  return "?";
+}
+
+int main(int argc, char** argv) {
+  std::string path = (argc > 1) ? argv[1] : "";
+  TestProvider provider = TestProvider::load(path);
+
+  // functions list
+  std::vector<std::string> fns = provider.functions();
+  std::cout << "functions: ";
+  for (size_t i = 0; i < fns.size(); i++) {
+    if (i) std::cout << ", ";
+    std::cout << fns[i];
+  }
+  std::cout << "\n";
+
+  // tally over all entries
+  size_t total = 0;
+  size_t valueN = 0, absentN = 0, matchN = 0, errorN = 0;
+  size_t inN = 0, argsN = 0, ctxN = 0;
+  for (const auto& fn : fns) {
+    for (const auto& e : provider.entries(fn)) {
+      total++;
+      switch (e.expect.kind) {
+        case ExpectKind::VALUE:
+          valueN++;
+          break;
+        case ExpectKind::ABSENT:
+          absentN++;
+          break;
+        case ExpectKind::MATCH:
+          matchN++;
+          break;
+        case ExpectKind::ERROR:
+          errorN++;
+          break;
+      }
+      switch (e.input.kind) {
+        case InputKind::IN:
+          inN++;
+          break;
+        case InputKind::ARGS:
+          argsN++;
+          break;
+        case InputKind::CTX:
+          ctxN++;
+          break;
+      }
+    }
+  }
+
+  std::cout << "total entries: " << total << " ; expect kinds: value=" << valueN
+            << ", absent=" << absentN << ", match=" << matchN << ", error=" << errorN
+            << " ; input kinds: in=" << inN;
+  if (argsN) std::cout << ", args=" << argsN;
+  if (ctxN) std::cout << ", ctx=" << ctxN;
+  std::cout << "\n";
+
+  // getpath/basic[0]
+  std::vector<Entry> gp = provider.entries("getpath", std::optional<std::string>("basic"));
+  if (!gp.empty()) {
+    const Entry& e = gp[0];
+    std::cout << "getpath/basic[0]: id=" << (e.id ? *e.id : std::string("null"))
+              << ", doc=" << (e.doc ? "true" : "false")
+              << ", input.kind=" << inputKindName(e.input.kind)
+              << ", expect.kind=" << expectKindName(e.expect.kind) << ", expect.value=";
+    if (e.expect.value.has_value())
+      std::cout << jsonify(*e.expect.value);
+    else
+      std::cout << "(none)";
+    std::cout << "\n";
+  }
+
+  return 0;
+}
diff --git a/test/proto/csharp/Provider.cs b/test/proto/csharp/Provider.cs
new file mode 100644
index 0000000..5f087b4
--- /dev/null
+++ b/test/proto/csharp/Provider.cs
@@ -0,0 +1,829 @@
+// Test Provider (prototype) — C# port of the canonical TypeScript
+// implementation (../ts/provider.ts).
+//
+// Reads the shared corpus (build/test/test.json) and hands test code clean,
+// normalized cases. It is NOT a test runner: it never calls the subject and
+// never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+//
+// Zero runtime dependencies (.NET standard library only — System.Text.Json is
+// part of the BCL), matching repo policy.
+
+using System.Collections;
+using System.Globalization;
+using System.Runtime.CompilerServices;
+using System.Text;
+using System.Text.Json;
+using System.Text.RegularExpressions;
+
+namespace Voxgig.Struct.Proto;
+
+public enum InputKind { In, Args, Ctx }
+
+public enum ExpectKind { Value, Error, Match, Absent }
+
+// Input is a tagged invocation: exactly one of In/Args/Ctx is meaningful,
+// selected by Kind (mirrors the runner's ctx -> args -> in precedence).
+public sealed class Input
+{
+    public InputKind Kind;
+    public object? In;                       // Kind==In  (absent => null)
+    public List<object?>? Args;              // Kind==Args
+    public Dictionary<string, object?>? Ctx; // Kind==Ctx
+}
+
+// ErrorCheck is the parsed form of a raw `err` spec.
+public sealed class ErrorCheck
+{
+    public bool Any;
+    public string? Text;
+    public bool Regex;
+}
+
+// Expect is a tagged expectation: value | error | match | absent.
+public sealed class Expect
+{
+    public ExpectKind Kind;
+    public bool HasValue;       // distinguishes present-null from absent
+    public object? Value;       // Kind==Value
+    public ErrorCheck? Error;   // Kind==Error
+    public object? Match;       // populated whenever a `match` key is present
+}
+
+// Entry is the normalized record for a single corpus test case.
+public sealed class Entry
+{
+    public string Function = "";
+    public string Group = "";
+    public int Index;
+    public string? Id;
+    public bool Doc;
+    public string? Client;
+    public Input Input = new();
+    public Expect Expect = new();
+    public object? Raw;
+}
+
+// MatchResult is the outcome of a structural match.
+public sealed class MatchResult
+{
+    public bool Ok;
+    public List<string>? Path;
+    public object? Expected;
+    public object? Actual;
+}
+
+public sealed class TestProvider
+{
+    public const string NULLMARK   = "__NULL__";
+    public const string UNDEFMARK  = "__UNDEF__";
+    public const string EXISTSMARK = "__EXISTS__";
+
+    // The parsed corpus as native objects. Objects are represented by
+    // OrderedMap so corpus property order (preserved by JsonDocument's
+    // EnumerateObject) is retained for Functions()/Groups().
+    private readonly object? _spec;
+
+    private TestProvider(object? spec)
+    {
+        _spec = spec;
+    }
+
+    // Default corpus path: build/test/test.json relative to the repo root,
+    // resolved from this source file's location so it works regardless of cwd.
+    private static string DefaultTestFile([CallerFilePath] string here = "")
+    {
+        // here = .../test/proto/csharp/Provider.cs
+        string dir = Path.GetDirectoryName(here)!; // test/proto/csharp
+        return Path.GetFullPath(
+            Path.Combine(dir, "..", "..", "..", "build", "test", "test.json"));
+    }
+
+    public static TestProvider Load(string? testfile = null)
+    {
+        string file = testfile ?? DefaultTestFile();
+        string json = File.ReadAllText(file);
+        using var doc = JsonDocument.Parse(json);
+        return new TestProvider(Convert(doc.RootElement));
+    }
+
+    // Raw returns the parsed test.json (escape hatch).
+    public object? Raw() => _spec;
+
+    // root returns spec.struct if present, else spec itself, as an OrderedMap.
+    private OrderedMap? Root()
+    {
+        if (_spec is OrderedMap m)
+        {
+            if (m.TryGetValue("struct", out object? s) && s is OrderedMap sm)
+            {
+                return sm;
+            }
+            return m;
+        }
+        return null;
+    }
+
+    // fnNode resolves the node for a function (under struct, falling back to root).
+    private OrderedMap? FnNode(string fn)
+    {
+        if (_spec is OrderedMap m)
+        {
+            if (m.TryGetValue("struct", out object? s) && s is OrderedMap sm
+                && sm.TryGetValue(fn, out object? n) && n is OrderedMap nm)
+            {
+                return nm;
+            }
+            if (m.TryGetValue(fn, out object? n2) && n2 is OrderedMap nm2)
+            {
+                return nm2;
+            }
+        }
+        return null;
+    }
+
+    // Functions lists the function names in corpus order.
+    public List<string> Functions()
+    {
+        var root = Root();
+        var output = new List<string>();
+        if (root == null)
+        {
+            return output;
+        }
+        foreach (string k in root.Keys)
+        {
+            object? v = root[k];
+            if (IsGroupBag(v) || HasGroups(v))
+            {
+                output.Add(k);
+            }
+        }
+        return output;
+    }
+
+    // Groups lists the group names for a function in corpus order.
+    public List<string> Groups(string fn)
+    {
+        var node = FnNode(fn) ?? throw new ArgumentException($"Unknown function: {fn}");
+        var output = new List<string>();
+        foreach (string k in node.Keys)
+        {
+            if (k != "name" && IsGroupBag(node[k]))
+            {
+                output.Add(k);
+            }
+        }
+        return output;
+    }
+
+    // Entries returns all entries for a function, or for one specific group.
+    public List<Entry> Entries(string fn, string? group = null)
+    {
+        var node = FnNode(fn) ?? throw new ArgumentException($"Unknown function: {fn}");
+        var groups = group != null ? new List<string> { group } : Groups(fn);
+        var output = new List<Entry>();
+        foreach (string g in groups)
+        {
+            if (!node.TryGetValue(g, out object? bagVal) || bagVal is not OrderedMap bag
+                || !IsGroupBag(bag))
+            {
+                continue;
+            }
+            if (!bag.TryGetValue("set", out object? setVal) || setVal is not List<object?> set)
+            {
+                continue;
+            }
+            for (int i = 0; i < set.Count; i++)
+            {
+                output.Add(Normalize(fn, g, i, set[i] as OrderedMap));
+            }
+        }
+        return output;
+    }
+
+    // ─── shape predicates ──────────────────────────────────────────────────
+
+    // A group bag is a map with a `set` array.
+    private static bool IsGroupBag(object? v)
+        => v is OrderedMap m && m.TryGetValue("set", out object? s) && s is List<object?>;
+
+    // A function node has at least one child group bag (besides `name`).
+    private static bool HasGroups(object? v)
+    {
+        if (v is not OrderedMap m)
+        {
+            return false;
+        }
+        foreach (string k in m.Keys)
+        {
+            if (k != "name" && IsGroupBag(m[k]))
+            {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    // ─── normalization ─────────────────────────────────────────────────────
+
+    private static Entry Normalize(string fn, string group, int index, OrderedMap? raw)
+    {
+        raw ??= new OrderedMap();
+        string? id = (Has(raw, "id") && raw["id"] != null) ? Stringify(raw["id"]) : null;
+        string? client = (Has(raw, "client") && raw["client"] != null)
+            ? Stringify(raw["client"]) : null;
+        bool doc = raw.TryGetValue("doc", out object? dv) && dv is bool db && db;
+        return new Entry
+        {
+            Function = fn,
+            Group = group,
+            Index = index,
+            Id = id,
+            Doc = doc,
+            Client = client,
+            Input = ResolveInput(raw),
+            Expect = ResolveExpect(raw),
+            Raw = raw,
+        };
+    }
+
+    private static bool Has(OrderedMap raw, string key) => raw.ContainsKey(key);
+
+    private static Input ResolveInput(OrderedMap raw)
+    {
+        if (Has(raw, "ctx"))
+        {
+            return new Input { Kind = InputKind.Ctx, Ctx = raw["ctx"] as Dictionary<string, object?> ?? AsDict(raw["ctx"]) };
+        }
+        if (Has(raw, "args"))
+        {
+            return new Input { Kind = InputKind.Args, Args = raw["args"] as List<object?> };
+        }
+        // Kind==In: key absent => native null.
+        return new Input { Kind = InputKind.In, In = Has(raw, "in") ? raw["in"] : null };
+    }
+
+    private static Dictionary<string, object?>? AsDict(object? v)
+    {
+        if (v is OrderedMap m)
+        {
+            var d = new Dictionary<string, object?>();
+            foreach (string k in m.Keys)
+            {
+                d[k] = m[k];
+            }
+            return d;
+        }
+        return null;
+    }
+
+    private static readonly Regex ReErr = new(@"^/(.+)/$", RegexOptions.Compiled);
+
+    private static ErrorCheck ParseErr(object? err)
+    {
+        if (err is bool b && b)
+        {
+            return new ErrorCheck { Any = true, Text = null, Regex = false };
+        }
+        if (err is string s)
+        {
+            Match m = ReErr.Match(s);
+            if (m.Success)
+            {
+                return new ErrorCheck { Any = false, Text = m.Groups[1].Value, Regex = true };
+            }
+            return new ErrorCheck { Any = false, Text = s, Regex = false };
+        }
+        // Non-true, non-string err spec: treat as "any error".
+        return new ErrorCheck { Any = true, Text = null, Regex = false };
+    }
+
+    private static Expect ResolveExpect(OrderedMap raw)
+    {
+        bool hasMatch = Has(raw, "match");
+        object? matchPart = hasMatch ? raw["match"] : null;
+        if (Has(raw, "err"))
+        {
+            return new Expect { Kind = ExpectKind.Error, Error = ParseErr(raw["err"]), Match = matchPart };
+        }
+        if (Has(raw, "out"))
+        {
+            return new Expect { Kind = ExpectKind.Value, HasValue = true, Value = raw["out"], Match = matchPart };
+        }
+        if (hasMatch)
+        {
+            return new Expect { Kind = ExpectKind.Match, Match = matchPart };
+        }
+        return new Expect { Kind = ExpectKind.Absent };
+    }
+
+    // ─── pure comparison helpers ───────────────────────────────────────────
+
+    public static string Stringify(object? x)
+        => x is string s ? s : CompactJson(x);
+
+    private static object? NormNull(object? x)
+    {
+        if (x is string s && s == NULLMARK)
+        {
+            return null;
+        }
+        if (x == null)
+        {
+            return null;
+        }
+        if (x is List<object?> list)
+        {
+            var output = new List<object?>(list.Count);
+            foreach (object? e in list)
+            {
+                output.Add(NormNull(e));
+            }
+            return output;
+        }
+        if (x is OrderedMap map)
+        {
+            var output = new OrderedMap();
+            foreach (string k in map.Keys)
+            {
+                output[k] = NormNull(map[k]);
+            }
+            return output;
+        }
+        return x;
+    }
+
+    private static object? NormMark(object? x)
+    {
+        if (x is string s && s == NULLMARK)
+        {
+            return null;
+        }
+        if (x is List<object?> list)
+        {
+            var output = new List<object?>(list.Count);
+            foreach (object? e in list)
+            {
+                output.Add(NormMark(e));
+            }
+            return output;
+        }
+        if (x is OrderedMap map)
+        {
+            var output = new OrderedMap();
+            foreach (string k in map.Keys)
+            {
+                output[k] = NormMark(map[k]);
+            }
+            return output;
+        }
+        return x;
+    }
+
+    // Matchval reproduces the runner's scalar match: equal, then string rules.
+    public static bool Matchval(object? check, object? @base)
+    {
+        if (ScalarEq(check, @base))
+        {
+            return true;
+        }
+        if (check is string cs)
+        {
+            string basestr = Stringify(@base);
+            Match m = ReErr.Match(cs);
+            if (m.Success)
+            {
+                try
+                {
+                    return Regex.IsMatch(basestr, m.Groups[1].Value);
+                }
+                catch (ArgumentException)
+                {
+                    return false;
+                }
+            }
+            return basestr.ToLowerInvariant().Contains(cs.ToLowerInvariant());
+        }
+        return false;
+    }
+
+    // Equal is deep equality collapsing "__NULL__" and null to null on both sides
+    // (runner default null:true).
+    public static bool Equal(object? expected, object? actual)
+        => DeepEq(NormNull(expected), NormNull(actual));
+
+    // EqualStrict is deep equality normalizing only "__NULL__" to null
+    // (runner null:false functions; absent stays distinct from null).
+    public static bool EqualStrict(object? expected, object? actual)
+        => DeepEq(NormMark(expected), NormMark(actual));
+
+    private static bool DeepEq(object? a, object? b)
+    {
+        if (ScalarEq(a, b))
+        {
+            return true;
+        }
+        if (a is List<object?> al && b is List<object?> bl)
+        {
+            if (al.Count != bl.Count)
+            {
+                return false;
+            }
+            for (int i = 0; i < al.Count; i++)
+            {
+                if (!DeepEq(al[i], bl[i]))
+                {
+                    return false;
+                }
+            }
+            return true;
+        }
+        if (a is OrderedMap am && b is OrderedMap bm)
+        {
+            if (am.Count != bm.Count)
+            {
+                return false;
+            }
+            foreach (string k in am.Keys)
+            {
+                if (!bm.TryGetValue(k, out object? bv) || !DeepEq(am[k], bv))
+                {
+                    return false;
+                }
+            }
+            return true;
+        }
+        return false;
+    }
+
+    // ScalarEq compares scalars; numeric values compare by value across
+    // long/double. null==null is true here.
+    private static bool ScalarEq(object? a, object? b)
+    {
+        if (a == null && b == null)
+        {
+            return true;
+        }
+        if (a == null || b == null)
+        {
+            return false;
+        }
+        bool aNum = TryToDouble(a, out double ad);
+        bool bNum = TryToDouble(b, out double bd);
+        if (aNum && bNum)
+        {
+            return ad == bd;
+        }
+        if (aNum != bNum)
+        {
+            return false;
+        }
+        if (a is string sa && b is string sb)
+        {
+            return sa == sb;
+        }
+        if (a is bool ba && b is bool bb)
+        {
+            return ba == bb;
+        }
+        return false;
+    }
+
+    private static bool TryToDouble(object? v, out double d)
+    {
+        switch (v)
+        {
+            case long l: d = l; return true;
+            case int i: d = i; return true;
+            case double db: d = db; return true;
+            case float f: d = f; return true;
+            default: d = 0; return false;
+        }
+    }
+
+    // ErrorMatches checks an ErrorCheck against a thrown message.
+    public static bool ErrorMatches(ErrorCheck check, string message)
+    {
+        if (check.Any)
+        {
+            return true;
+        }
+        if (check.Text == null)
+        {
+            return false;
+        }
+        if (check.Regex)
+        {
+            try
+            {
+                return Regex.IsMatch(message, check.Text);
+            }
+            catch (ArgumentException)
+            {
+                return false;
+            }
+        }
+        return message.ToLowerInvariant().Contains(check.Text.ToLowerInvariant());
+    }
+
+    // StructMatch performs a partial structural match: every leaf of check must
+    // match base at its path. First failure returns its path + the two values.
+    public static MatchResult StructMatch(object? check, object? @base)
+    {
+        var result = new MatchResult { Ok = true };
+        WalkLeaves(check, new List<string>(), (val, path) =>
+        {
+            if (!result.Ok)
+            {
+                return;
+            }
+            (object? baseval, bool found) = GetPath(@base, path);
+            if (found && ScalarEq(baseval, val))
+            {
+                return;
+            }
+            if (val is string us && us == UNDEFMARK && (!found || baseval == null))
+            {
+                return;
+            }
+            if (val is string es && es == EXISTSMARK && found && baseval != null)
+            {
+                return;
+            }
+            if (!Matchval(val, baseval))
+            {
+                result = new MatchResult { Ok = false, Path = path, Expected = val, Actual = baseval };
+            }
+        });
+        return result;
+    }
+
+    private static void WalkLeaves(object? node, List<string> path, Action<object?, List<string>> fn)
+    {
+        if (node is List<object?> list)
+        {
+            for (int i = 0; i < list.Count; i++)
+            {
+                WalkLeaves(list[i], AppendPath(path, i.ToString(CultureInfo.InvariantCulture)), fn);
+            }
+        }
+        else if (node is OrderedMap map)
+        {
+            foreach (string k in map.Keys)
+            {
+                WalkLeaves(map[k], AppendPath(path, k), fn);
+            }
+        }
+        else
+        {
+            fn(node, path);
+        }
+    }
+
+    private static List<string> AppendPath(List<string> path, string key)
+    {
+        var output = new List<string>(path.Count + 1);
+        output.AddRange(path);
+        output.Add(key);
+        return output;
+    }
+
+    // GetPath descends store following path. The bool reports whether the leaf
+    // was present (false means it ran off a null or a missing key/index).
+    private static (object?, bool) GetPath(object? store, List<string> path)
+    {
+        object? cur = store;
+        foreach (string key in path)
+        {
+            if (cur == null)
+            {
+                return (null, false);
+            }
+            if (cur is OrderedMap map)
+            {
+                if (!map.TryGetValue(key, out object? v))
+                {
+                    return (null, false);
+                }
+                cur = v;
+            }
+            else if (cur is List<object?> list)
+            {
+                if (!int.TryParse(key, NumberStyles.Integer, CultureInfo.InvariantCulture, out int idx)
+                    || idx < 0 || idx >= list.Count)
+                {
+                    return (null, false);
+                }
+                cur = list[idx];
+            }
+            else
+            {
+                return (null, false);
+            }
+        }
+        return (cur, true);
+    }
+
+    // ─── JSON conversion + compact serialization ───────────────────────────
+
+    // Convert a JsonElement tree into native objects. Objects become OrderedMap
+    // (document order preserved via EnumerateObject); arrays become
+    // List<object?>; numbers become long when integral, else double — so that
+    // an integer like 42 prints as "42", not "42.0".
+    private static object? Convert(JsonElement el)
+    {
+        switch (el.ValueKind)
+        {
+            case JsonValueKind.Object:
+            {
+                var m = new OrderedMap();
+                foreach (JsonProperty p in el.EnumerateObject())
+                {
+                    m[p.Name] = Convert(p.Value);
+                }
+                return m;
+            }
+            case JsonValueKind.Array:
+            {
+                var list = new List<object?>();
+                foreach (JsonElement e in el.EnumerateArray())
+                {
+                    list.Add(Convert(e));
+                }
+                return list;
+            }
+            case JsonValueKind.String:
+                return el.GetString();
+            case JsonValueKind.Number:
+                return el.TryGetInt64(out long l) ? l : el.GetDouble();
+            case JsonValueKind.True:
+                return true;
+            case JsonValueKind.False:
+                return false;
+            case JsonValueKind.Null:
+            default:
+                return null;
+        }
+    }
+
+    // CompactJson serializes a native value tree to compact JSON, mirroring
+    // JSON.stringify for the value shapes the corpus produces.
+    private static string CompactJson(object? x)
+    {
+        var sb = new StringBuilder();
+        WriteJson(sb, x);
+        return sb.ToString();
+    }
+
+    private static void WriteJson(StringBuilder sb, object? x)
+    {
+        switch (x)
+        {
+            case null:
+                sb.Append("null");
+                break;
+            case bool b:
+                sb.Append(b ? "true" : "false");
+                break;
+            case string s:
+                WriteJsonString(sb, s);
+                break;
+            case long l:
+                sb.Append(l.ToString(CultureInfo.InvariantCulture));
+                break;
+            case int i:
+                sb.Append(i.ToString(CultureInfo.InvariantCulture));
+                break;
+            case double d:
+                sb.Append(FormatDouble(d));
+                break;
+            case float f:
+                sb.Append(FormatDouble(f));
+                break;
+            case OrderedMap map:
+            {
+                sb.Append('{');
+                bool first = true;
+                foreach (string k in map.Keys)
+                {
+                    if (!first)
+                    {
+                        sb.Append(',');
+                    }
+                    first = false;
+                    WriteJsonString(sb, k);
+                    sb.Append(':');
+                    WriteJson(sb, map[k]);
+                }
+                sb.Append('}');
+                break;
+            }
+            case IDictionary dict:
+            {
+                sb.Append('{');
+                bool first = true;
+                foreach (DictionaryEntry de in dict)
+                {
+                    if (!first)
+                    {
+                        sb.Append(',');
+                    }
+                    first = false;
+                    WriteJsonString(sb, de.Key?.ToString() ?? "");
+                    sb.Append(':');
+                    WriteJson(sb, de.Value);
+                }
+                sb.Append('}');
+                break;
+            }
+            case IEnumerable en:
+            {
+                sb.Append('[');
+                bool first = true;
+                foreach (object? e in en)
+                {
+                    if (!first)
+                    {
+                        sb.Append(',');
+                    }
+                    first = false;
+                    WriteJson(sb, e);
+                }
+                sb.Append(']');
+                break;
+            }
+            default:
+                WriteJsonString(sb, x.ToString() ?? "");
+                break;
+        }
+    }
+
+    private static string FormatDouble(double d)
+    {
+        // Integral doubles print without a decimal point (JSON.stringify style).
+        if (d == Math.Floor(d) && !double.IsInfinity(d))
+        {
+            return ((long)d).ToString(CultureInfo.InvariantCulture);
+        }
+        return d.ToString("R", CultureInfo.InvariantCulture);
+    }
+
+    private static void WriteJsonString(StringBuilder sb, string s)
+    {
+        sb.Append('"');
+        foreach (char c in s)
+        {
+            switch (c)
+            {
+                case '"': sb.Append("\\\""); break;
+                case '\\': sb.Append("\\\\"); break;
+                case '\b': sb.Append("\\b"); break;
+                case '\f': sb.Append("\\f"); break;
+                case '\n': sb.Append("\\n"); break;
+                case '\r': sb.Append("\\r"); break;
+                case '\t': sb.Append("\\t"); break;
+                default:
+                    if (c < 0x20)
+                    {
+                        sb.Append("\\u").Append(((int)c).ToString("x4", CultureInfo.InvariantCulture));
+                    }
+                    else
+                    {
+                        sb.Append(c);
+                    }
+                    break;
+            }
+        }
+        sb.Append('"');
+    }
+}
+
+// OrderedMap is an insertion-ordered string-keyed map. Dictionary<,> does not
+// contractually preserve order; this thin wrapper guarantees corpus property
+// order for Functions()/Groups() and faithful structural walks.
+public sealed class OrderedMap
+{
+    private readonly List<string> _keys = new();
+    private readonly Dictionary<string, object?> _map = new();
+
+    public IReadOnlyList<string> Keys => _keys;
+
+    public int Count => _keys.Count;
+
+    public object? this[string key]
+    {
+        get => _map[key];
+        set
+        {
+            if (!_map.ContainsKey(key))
+            {
+                _keys.Add(key);
+            }
+            _map[key] = value;
+        }
+    }
+
+    public bool ContainsKey(string key) => _map.ContainsKey(key);
+
+    public bool TryGetValue(string key, out object? value) => _map.TryGetValue(key, out value);
+}
diff --git a/test/proto/csharp/Smoke.cs b/test/proto/csharp/Smoke.cs
new file mode 100644
index 0000000..a5f62bb
--- /dev/null
+++ b/test/proto/csharp/Smoke.cs
@@ -0,0 +1,75 @@
+// Smoke test for the C# test-provider port. Loads the default corpus and prints
+// summary numbers to verify parity with the canonical TS reference.
+//
+// Expected canonical output:
+//   functions: minor, getpath, inject, merge, transform, walk, validate, select, sentinels
+//   total entries: 1325 ; expect kinds: value=1181, absent=84, match=1, error=59 ; input kinds: in=1325
+//   getpath/basic[0]: id=getpath/basic#deep, doc=true, input.kind=in, expect.kind=value, expect.value=42
+
+namespace Voxgig.Struct.Proto;
+
+public static class Smoke
+{
+    private static string ExpectName(ExpectKind k) => k switch
+    {
+        ExpectKind.Value => "value",
+        ExpectKind.Error => "error",
+        ExpectKind.Match => "match",
+        ExpectKind.Absent => "absent",
+        _ => "?",
+    };
+
+    private static string InputName(InputKind k) => k switch
+    {
+        InputKind.In => "in",
+        InputKind.Args => "args",
+        InputKind.Ctx => "ctx",
+        _ => "?",
+    };
+
+    public static void Main()
+    {
+        TestProvider provider = TestProvider.Load();
+
+        List<string> fns = provider.Functions();
+        Console.WriteLine("functions: " + string.Join(", ", fns));
+
+        int total = 0;
+        var expectKinds = new Dictionary<string, int>
+        {
+            ["value"] = 0, ["absent"] = 0, ["match"] = 0, ["error"] = 0,
+        };
+        var inputKinds = new Dictionary<string, int>
+        {
+            ["in"] = 0, ["args"] = 0, ["ctx"] = 0,
+        };
+
+        foreach (string fn in fns)
+        {
+            foreach (Entry e in provider.Entries(fn))
+            {
+                total++;
+                expectKinds[ExpectName(e.Expect.Kind)]++;
+                inputKinds[InputName(e.Input.Kind)]++;
+            }
+        }
+
+        Console.WriteLine(
+            $"total entries: {total} ; " +
+            $"expect kinds: value={expectKinds["value"]}, absent={expectKinds["absent"]}, " +
+            $"match={expectKinds["match"]}, error={expectKinds["error"]} ; " +
+            $"input kinds: in={inputKinds["in"]}");
+
+        List<Entry> gp = provider.Entries("getpath", "basic");
+        if (gp.Count > 0)
+        {
+            Entry e = gp[0];
+            string id = e.Id ?? "<nil>";
+            string val = TestProvider.Stringify(e.Expect.Value);
+            Console.WriteLine(
+                $"getpath/basic[0]: id={id}, doc={(e.Doc ? "true" : "false")}, " +
+                $"input.kind={InputName(e.Input.Kind)}, expect.kind={ExpectName(e.Expect.Kind)}, " +
+                $"expect.value={val}");
+        }
+    }
+}
diff --git a/test/proto/csharp/StructProto.csproj b/test/proto/csharp/StructProto.csproj
new file mode 100644
index 0000000..e604ac5
--- /dev/null
+++ b/test/proto/csharp/StructProto.csproj
@@ -0,0 +1,16 @@
+<!-- Test Provider (prototype): C# port of test/proto/ts/provider.ts.
+     DEPENDENCY-FREE: .NET standard library only. System.Text.Json is part of
+     the BCL (no NuGet packages). Build/run the smoke target with:
+       dotnet run (from this directory). -->
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <LangVersion>12</LangVersion>
+    <StartupObject>Voxgig.Struct.Proto.Smoke</StartupObject>
+    <AssemblyName>structproto-smoke</AssemblyName>
+    <RootNamespace>Voxgig.Struct.Proto</RootNamespace>
+  </PropertyGroup>
+</Project>
diff --git a/test/proto/dart/provider.dart b/test/proto/dart/provider.dart
new file mode 100644
index 0000000..d8909c1
--- /dev/null
+++ b/test/proto/dart/provider.dart
@@ -0,0 +1,479 @@
+// Test Provider (prototype) — Dart port of the canonical TypeScript
+// implementation (../ts/provider.ts).
+//
+// Reads the shared corpus (build/test/test.json) and hands test code clean,
+// normalized cases. It is NOT a test runner: it never calls the subject and
+// never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+//
+// Zero runtime dependencies (Dart standard library only), matching repo policy.
+// dart:convert jsonDecode returns LinkedHashMap (insertion-ordered) for objects
+// and List for arrays, so corpus key order is preserved natively — unlike the
+// Go port, no separate order-tracking pass is needed. JSON numbers decode to
+// int (e.g. 42) when integral, double otherwise.
+
+import 'dart:convert';
+import 'dart:io';
+
+const String nullMark = '__NULL__';
+const String undefMark = '__UNDEF__';
+const String existsMark = '__EXISTS__';
+
+/// How the input is supplied to the subject (mirrors the runner's
+/// ctx → args → in precedence).
+enum InputKind { inp, args, ctx }
+
+/// How a result is expected (value | error | match | absent).
+enum ExpectKind { value, error, match, absent }
+
+/// A tagged invocation: exactly one of value/args/ctx is meaningful, selected
+/// by [kind]. The single-argument `in` value is named [value] because `in` is
+/// a reserved word in Dart.
+class Input {
+  final InputKind kind;
+  final dynamic value; // kind == InputKind.inp  — the single argument
+  final List<dynamic>? args; // kind == InputKind.args
+  final Map<String, dynamic>? ctx; // kind == InputKind.ctx
+
+  const Input(this.kind, {this.value, this.args, this.ctx});
+
+  String get kindName {
+    switch (kind) {
+      case InputKind.inp:
+        return 'in';
+      case InputKind.args:
+        return 'args';
+      case InputKind.ctx:
+        return 'ctx';
+    }
+  }
+}
+
+/// The parsed form of a raw `err` spec.
+class ErrorCheck {
+  final bool any;
+  final String? text;
+  final bool regex;
+
+  const ErrorCheck({required this.any, this.text, this.regex = false});
+}
+
+/// A tagged expectation: value | error | match | absent.
+class Expect {
+  final ExpectKind kind;
+  final bool hasValue; // distinguishes present-null from absent
+  final dynamic value; // kind == ExpectKind.value
+  final ErrorCheck? error; // kind == ExpectKind.error
+  final dynamic match; // populated whenever a `match` key is present
+
+  const Expect(
+    this.kind, {
+    this.hasValue = false,
+    this.value,
+    this.error,
+    this.match,
+  });
+
+  String get kindName {
+    switch (kind) {
+      case ExpectKind.value:
+        return 'value';
+      case ExpectKind.error:
+        return 'error';
+      case ExpectKind.match:
+        return 'match';
+      case ExpectKind.absent:
+        return 'absent';
+    }
+  }
+}
+
+/// The normalized record for a single corpus test case.
+class Entry {
+  final String function;
+  final String group;
+  final int index;
+  final String? id;
+  final bool doc;
+  final String? client;
+  final Input input;
+  final Expect expect;
+  final dynamic raw; // the original entry, untouched (escape hatch)
+
+  const Entry({
+    required this.function,
+    required this.group,
+    required this.index,
+    required this.id,
+    required this.doc,
+    required this.client,
+    required this.input,
+    required this.expect,
+    required this.raw,
+  });
+}
+
+/// The outcome of a structural match.
+class MatchResult {
+  final bool ok;
+  final List<String>? path;
+  final dynamic expected;
+  final dynamic actual;
+
+  const MatchResult(this.ok, {this.path, this.expected, this.actual});
+}
+
+/// Default corpus path: build/test/test.json relative to the repo root.
+///
+/// Resolved from the location of this source file (Platform.script), so it
+/// works regardless of the current working directory. This file lives at
+/// test/proto/dart/provider.dart, so the repo root is three directories up.
+/// When Platform.script does not point at a file path (e.g. some snapshot
+/// runs) we fall back to the documented relative path used by the runner.
+String _defaultTestFile() {
+  try {
+    final script = Platform.script;
+    if (script.scheme == 'file') {
+      // .../test/proto/dart/<entrypoint>.dart -> repo root is 4 segments up.
+      final dir = File.fromUri(script).parent; // test/proto/dart (or smoke dir)
+      // Walk up to repo root: dart -> proto -> test -> root.
+      final root = dir.parent.parent.parent;
+      return '${root.path}/build/test/test.json';
+    }
+  } catch (_) {
+    // Fall through to the relative default below.
+  }
+  // Documented fallback (matches dart/test/runner.dart's relative default,
+  // adjusted for this file's deeper location): run from the repo root.
+  return 'build/test/test.json';
+}
+
+/// Holds the parsed corpus.
+class TestProvider {
+  final dynamic spec;
+
+  const TestProvider(this.spec);
+
+  /// Parse test.json. A null [path] means the default corpus path.
+  static TestProvider load([String? path]) {
+    final file = path ?? _defaultTestFile();
+    final raw = File(file).readAsStringSync();
+    return TestProvider(jsonDecode(raw));
+  }
+
+  /// The parsed test.json (escape hatch).
+  dynamic raw() => spec;
+
+  /// spec.struct if present, else spec itself, as a Map.
+  Map<String, dynamic>? _root() {
+    if (spec is Map) {
+      final m = spec as Map;
+      final st = m['struct'];
+      if (st is Map) {
+        return _asStrMap(st);
+      }
+      return _asStrMap(m);
+    }
+    return null;
+  }
+
+  /// Resolve the node for a function (under struct, falling back to root).
+  Map<String, dynamic> _fnNode(String fn) {
+    if (spec is Map) {
+      final m = spec as Map;
+      final st = m['struct'];
+      if (st is Map && st[fn] is Map) {
+        return _asStrMap(st[fn] as Map);
+      }
+      if (m[fn] is Map) {
+        return _asStrMap(m[fn] as Map);
+      }
+    }
+    throw StateError('Unknown function: $fn');
+  }
+
+  /// The function names, in corpus order.
+  List<String> functions() {
+    final root = _root();
+    if (root == null) return <String>[];
+    final out = <String>[];
+    for (final k in root.keys) {
+      final v = root[k];
+      if (_isGroupBag(v) || _hasGroups(v)) {
+        out.add(k);
+      }
+    }
+    return out;
+  }
+
+  /// The group names for a function, in corpus order.
+  List<String> groups(String fn) {
+    final node = _fnNode(fn);
+    final out = <String>[];
+    for (final k in node.keys) {
+      if (k != 'name' && _isGroupBag(node[k])) {
+        out.add(k);
+      }
+    }
+    return out;
+  }
+
+  /// All entries for a function, or for one specific group.
+  List<Entry> entries(String fn, [String? group]) {
+    final node = _fnNode(fn);
+    final groupNames = group != null ? <String>[group] : groups(fn);
+    final out = <Entry>[];
+    for (final g in groupNames) {
+      final bag = node[g];
+      if (!_isGroupBag(bag)) continue;
+      final set = (bag as Map)['set'];
+      if (set is! List) continue;
+      for (var i = 0; i < set.length; i++) {
+        out.add(_normalize(fn, g, i, set[i]));
+      }
+    }
+    return out;
+  }
+}
+
+Map<String, dynamic> _asStrMap(Map m) {
+  if (m is Map<String, dynamic>) return m;
+  final o = <String, dynamic>{};
+  m.forEach((k, v) => o[k.toString()] = v);
+  return o;
+}
+
+/// A group bag is a Map with a `set` List.
+bool _isGroupBag(dynamic v) => v is Map && v['set'] is List;
+
+/// A function node has at least one child group bag.
+bool _hasGroups(dynamic v) {
+  if (v is! Map) return false;
+  for (final k in v.keys) {
+    if (k != 'name' && _isGroupBag(v[k])) return true;
+  }
+  return false;
+}
+
+bool _has(dynamic m, String key) => m is Map && m.containsKey(key);
+
+Entry _normalize(String fn, String group, int index, dynamic raw) {
+  String? id;
+  if (_has(raw, 'id') && (raw as Map)['id'] != null) {
+    id = _stringify(raw['id']);
+  }
+  String? client;
+  if (_has(raw, 'client') && (raw as Map)['client'] != null) {
+    client = _stringify(raw['client']);
+  }
+  final doc = raw is Map && raw['doc'] == true;
+  return Entry(
+    function: fn,
+    group: group,
+    index: index,
+    id: id,
+    doc: doc,
+    client: client,
+    input: _resolveInput(raw),
+    expect: _resolveExpect(raw),
+    raw: raw,
+  );
+}
+
+Input _resolveInput(dynamic raw) {
+  if (_has(raw, 'ctx')) {
+    final ctx = (raw as Map)['ctx'];
+    return Input(InputKind.ctx, ctx: ctx is Map ? _asStrMap(ctx) : null);
+  }
+  if (_has(raw, 'args')) {
+    final args = (raw as Map)['args'];
+    return Input(InputKind.args,
+        args: args is List ? List<dynamic>.from(args) : null);
+  }
+  // kind == in: key absent => native null.
+  return Input(InputKind.inp, value: _has(raw, 'in') ? (raw as Map)['in'] : null);
+}
+
+final RegExp _reErr = RegExp(r'^/(.+)/$');
+
+ErrorCheck _parseErr(dynamic err) {
+  if (err == true) {
+    return const ErrorCheck(any: true);
+  }
+  if (err is String) {
+    final m = _reErr.firstMatch(err);
+    if (m != null) {
+      return ErrorCheck(any: false, text: m.group(1), regex: true);
+    }
+    return ErrorCheck(any: false, text: err, regex: false);
+  }
+  // Non-true, non-string err spec: treat as "any error".
+  return const ErrorCheck(any: true);
+}
+
+Expect _resolveExpect(dynamic raw) {
+  final hasMatch = _has(raw, 'match');
+  final matchPart = hasMatch ? (raw as Map)['match'] : null;
+  if (_has(raw, 'err')) {
+    return Expect(ExpectKind.error,
+        error: _parseErr((raw as Map)['err']), match: matchPart);
+  }
+  if (_has(raw, 'out')) {
+    // KEY PRESENCE: "out" present even if null => value.
+    return Expect(ExpectKind.value,
+        hasValue: true, value: (raw as Map)['out'], match: matchPart);
+  }
+  if (hasMatch) {
+    return Expect(ExpectKind.match, match: matchPart);
+  }
+  return const Expect(ExpectKind.absent);
+}
+
+// ─── pure comparison helpers ───────────────────────────────────────────────
+
+/// The string itself if [x] is a String, else compact JSON. JSON-encoded ints
+/// print without a decimal point (42, not 42.0).
+String _stringify(dynamic x) => x is String ? x : jsonEncode(x);
+
+dynamic _normNull(dynamic x) {
+  if (x == nullMark || x == null) return null;
+  if (x is List) return x.map(_normNull).toList();
+  if (x is Map) {
+    final o = <String, dynamic>{};
+    x.forEach((k, v) => o[k.toString()] = _normNull(v));
+    return o;
+  }
+  return x;
+}
+
+dynamic _normMark(dynamic x) {
+  if (x == nullMark) return null;
+  if (x is List) return x.map(_normMark).toList();
+  if (x is Map) {
+    final o = <String, dynamic>{};
+    x.forEach((k, v) => o[k.toString()] = _normMark(v));
+    return o;
+  }
+  return x;
+}
+
+bool _deepEq(dynamic a, dynamic b) {
+  if (_scalarEq(a, b)) return true;
+  if (a is List && b is List) {
+    if (a.length != b.length) return false;
+    for (var i = 0; i < a.length; i++) {
+      if (!_deepEq(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  if (a is Map && b is Map) {
+    if (a.length != b.length) return false;
+    for (final k in a.keys) {
+      if (!b.containsKey(k) || !_deepEq(a[k], b[k])) return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+bool _scalarEq(dynamic a, dynamic b) {
+  if (a == null && b == null) return true;
+  if (a == null || b == null) return false;
+  if (a is num && b is num) return a == b;
+  if (a is String && b is String) return a == b;
+  if (a is bool && b is bool) return a == b;
+  return false;
+}
+
+/// `check === base`; else if check is a String: `"/re/"` ⇒ regex test against
+/// stringify(base), otherwise case-insensitive substring; else if check is a
+/// Function ⇒ true.
+bool matchval(dynamic check, dynamic base) {
+  if (equalStrict(check, base)) return true;
+  if (check is String) {
+    final basestr = _stringify(base);
+    final m = _reErr.firstMatch(check);
+    if (m != null) {
+      return RegExp(m.group(1)!).hasMatch(basestr);
+    }
+    return basestr.toLowerCase().contains(check.toLowerCase());
+  }
+  if (check is Function) return true;
+  return false;
+}
+
+/// Deep equality, null/undef collapsed (runner default null:true): "__NULL__"
+/// and null collapse to null on both sides.
+bool equal(dynamic expected, dynamic actual) =>
+    _deepEq(_normNull(expected), _normNull(actual));
+
+/// Deep equality where undefined ≠ null (runner null:false functions): only
+/// "__NULL__" is normalized to null.
+bool equalStrict(dynamic expected, dynamic actual) =>
+    _deepEq(_normMark(expected), _normMark(actual));
+
+/// An ErrorCheck against a thrown message: any ⇒ true; regex ⇒ RegExp test;
+/// else case-insensitive substring.
+bool errorMatches(ErrorCheck check, String message) {
+  if (check.any) return true;
+  if (check.text == null) return false;
+  if (check.regex) return RegExp(check.text!).hasMatch(message);
+  return message.toLowerCase().contains(check.text!.toLowerCase());
+}
+
+/// Partial structural match: every leaf of [check] must match [base] at its
+/// path. First failure returns its path plus the two values.
+MatchResult structMatch(dynamic check, dynamic base) {
+  var result = const MatchResult(true);
+  _walkLeaves(check, <String>[], (val, path) {
+    if (!result.ok) return;
+    final found = _getpath(base, path);
+    final baseval = found.value;
+    if (found.present && _scalarEq(baseval, val)) return;
+    if (val == undefMark && (!found.present || baseval == null)) return;
+    if (val == existsMark && found.present && baseval != null) return;
+    if (!matchval(val, baseval)) {
+      result = MatchResult(false, path: path, expected: val, actual: baseval);
+    }
+  });
+  return result;
+}
+
+void _walkLeaves(
+    dynamic node, List<String> path, void Function(dynamic, List<String>) fn) {
+  if (node is List) {
+    for (var i = 0; i < node.length; i++) {
+      _walkLeaves(node[i], [...path, i.toString()], fn);
+    }
+  } else if (node is Map) {
+    node.forEach((k, v) => _walkLeaves(v, [...path, k.toString()], fn));
+  } else {
+    fn(node, path);
+  }
+}
+
+class _Found {
+  final dynamic value;
+  final bool present;
+  const _Found(this.value, this.present);
+}
+
+/// Descend store following path. `present` is false if it ran off a null or a
+/// missing key/index.
+_Found _getpath(dynamic store, List<String> path) {
+  dynamic cur = store;
+  for (final key in path) {
+    if (cur is Map) {
+      if (!cur.containsKey(key)) return const _Found(null, false);
+      cur = cur[key];
+    } else if (cur is List) {
+      final idx = int.tryParse(key);
+      if (idx == null || idx < 0 || idx >= cur.length) {
+        return const _Found(null, false);
+      }
+      cur = cur[idx];
+    } else {
+      return const _Found(null, false);
+    }
+  }
+  return _Found(cur, true);
+}
diff --git a/test/proto/dart/smoke.dart b/test/proto/dart/smoke.dart
new file mode 100644
index 0000000..5924918
--- /dev/null
+++ b/test/proto/dart/smoke.dart
@@ -0,0 +1,57 @@
+// Smoke check (not a test): prove the provider loads and normalizes, and that
+// the summary numbers match the canonical TS reference.
+//
+// Run from the repo root once a Dart toolchain is available:
+//   dart run test/proto/dart/smoke.dart
+// or with an explicit corpus path:
+//   dart run test/proto/dart/smoke.dart build/test/test.json
+
+import 'provider.dart';
+
+void main(List<String> args) {
+  final p = args.isNotEmpty ? TestProvider.load(args[0]) : TestProvider.load();
+
+  final fns = p.functions();
+  print('functions: ${fns.join(', ')}');
+
+  var total = 0;
+  final expectKinds = <String, int>{};
+  final inputKinds = <String, int>{};
+  for (final fn in fns) {
+    for (final e in p.entries(fn)) {
+      total++;
+      expectKinds[e.expect.kindName] = (expectKinds[e.expect.kindName] ?? 0) + 1;
+      inputKinds[e.input.kindName] = (inputKinds[e.input.kindName] ?? 0) + 1;
+    }
+  }
+
+  print('total entries: $total');
+  print('expect kinds: value=${expectKinds['value'] ?? 0}, '
+      'absent=${expectKinds['absent'] ?? 0}, '
+      'match=${expectKinds['match'] ?? 0}, '
+      'error=${expectKinds['error'] ?? 0}');
+  print('input kinds: in=${inputKinds['in'] ?? 0}, '
+      'args=${inputKinds['args'] ?? 0}, '
+      'ctx=${inputKinds['ctx'] ?? 0}');
+
+  final gp = p.entries('getpath', 'basic');
+  if (gp.isNotEmpty) {
+    final e = gp[0];
+    print('getpath/basic[0]: id=${e.id}, doc=${e.doc}, '
+        'input.kind=${e.input.kindName}, expect.kind=${e.expect.kindName}, '
+        'expect.value=${e.expect.value}');
+  }
+
+  // helper sanity
+  print('equal(42,42): ${equal(42, 42)}');
+  print('equal(null,null): ${equal(null, null)}');
+  print('errorMatches(any): '
+      '${errorMatches(const ErrorCheck(any: true), 'boom')}');
+  print('errorMatches(substr): '
+      '${errorMatches(const ErrorCheck(any: false, text: 'not found'), 'Key NOT FOUND here')}');
+  print('structMatch ok: '
+      '${structMatch({'a': {'b': 2}}, {'a': {'b': 2}, 'c': 9}).ok}');
+  final sm = structMatch({'a': {'b': 2}}, {'a': {'b': 3}});
+  print('structMatch fail: ok=${sm.ok}, path=${sm.path}, '
+      'expected=${sm.expected}, actual=${sm.actual}');
+}
diff --git a/test/proto/elixir/provider.ex b/test/proto/elixir/provider.ex
new file mode 100644
index 0000000..42998c7
--- /dev/null
+++ b/test/proto/elixir/provider.ex
@@ -0,0 +1,602 @@
+# Test Provider (prototype) — Elixir port of the canonical ts/provider.ts.
+#
+# Reads the shared corpus (build/test/test.json) and hands test code clean,
+# normalized cases. It is NOT a test runner: it never calls the subject and
+# never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+#
+# Zero runtime dependencies: ships its OWN minimal JSON parser in pure Elixir
+# (no Jason/Poison, and no reliance on the OTP :json module being present),
+# matching repo policy.
+#
+# JSON value representation (Elixir maps do NOT preserve key order, which the
+# provider needs for functions()/groups()):
+#   * objects -> %Voxgig.Proto.Provider.Obj{order: [keys...], map: %{k => v}}
+#                (string keys; `order` records insertion order)
+#   * arrays  -> Elixir list
+#   * strings -> binary
+#   * numbers -> integer | float
+#   * boolean -> true | false
+#   * null    -> the :null atom (distinct from nil/absent)
+
+defmodule Voxgig.Proto.Provider do
+  # --- ordered JSON object -------------------------------------------------
+  defmodule Obj do
+    @moduledoc "Ordered JSON object: preserves key insertion order."
+    defstruct order: [], map: %{}
+
+    def new(pairs) when is_list(pairs) do
+      Enum.reduce(pairs, %Obj{}, fn {k, v}, acc -> put(acc, k, v) end)
+    end
+
+    def put(%Obj{order: order, map: map} = o, k, v) do
+      if Map.has_key?(map, k) do
+        %Obj{o | map: Map.put(map, k, v)}
+      else
+        %Obj{order: order ++ [k], map: Map.put(map, k, v)}
+      end
+    end
+
+    def has?(%Obj{map: map}, k), do: Map.has_key?(map, k)
+    def get(%Obj{map: map}, k, default \\ nil), do: Map.get(map, k, default)
+    def keys(%Obj{order: order}), do: order
+  end
+
+  alias Voxgig.Proto.Provider.Obj
+
+  @nullmark "__NULL__"
+  @undefmark "__UNDEF__"
+  @existsmark "__EXISTS__"
+
+  # Sentinel distinguishing "key absent" from "value is :null" in getpath.
+  @missing :__provider_missing__
+
+  # ---------------------------------------------------------------------------
+  # Public API surface (PROVIDER.md §6)
+  # ---------------------------------------------------------------------------
+
+  # Default corpus path: build/test/test.json relative to the repo root.
+  # This file lives at test/proto/elixir/provider.ex, so the repo root is three
+  # levels up.
+  def default_test_file do
+    here = Path.dirname(__ENV__.file)
+    Path.join([here, "..", "..", "..", "build", "test", "test.json"])
+  end
+
+  @doc "Parse a corpus file into a provider (the parsed spec)."
+  def load(testfile \\ nil) do
+    file = testfile || default_test_file()
+    file |> File.read!() |> parse_json()
+  end
+
+  @doc "The parsed test.json (escape hatch)."
+  def raw(provider), do: provider
+
+  @doc ~S(Function names: ["minor","getpath",...].)
+  def functions(provider) do
+    root = root_node(provider)
+
+    Obj.keys(root)
+    |> Enum.filter(fn k ->
+      v = Obj.get(root, k)
+      is_group_bag(v) or has_groups(v)
+    end)
+  end
+
+  @doc ~S(Group names for a function: ["basic","relative",...].)
+  def groups(provider, fn_name) do
+    node = fn_node(provider, fn_name)
+
+    Obj.keys(node)
+    |> Enum.filter(fn k -> k != "name" and is_group_bag(Obj.get(node, k)) end)
+  end
+
+  @doc "Normalized entries for a function, optionally a single group."
+  def entries(provider, fn_name, group \\ nil) do
+    node = fn_node(provider, fn_name)
+    group_names = if group != nil, do: [group], else: groups(provider, fn_name)
+
+    Enum.flat_map(group_names, fn g ->
+      bag = Obj.get(node, g)
+
+      if is_group_bag(bag) do
+        set = Obj.get(bag, "set")
+
+        set
+        |> Enum.with_index()
+        |> Enum.map(fn {entry, i} -> normalize(fn_name, g, i, entry) end)
+      else
+        []
+      end
+    end)
+  end
+
+  # The struct bag when present, else the top-level object.
+  defp root_node(provider) do
+    case provider do
+      %Obj{} = o ->
+        case Obj.get(o, "struct") do
+          %Obj{} = s -> s
+          _ -> o
+        end
+
+      _ ->
+        provider
+    end
+  end
+
+  defp fn_node(provider, fn_name) do
+    struct_root =
+      case provider do
+        %Obj{} = o -> Obj.get(o, "struct")
+        _ -> nil
+      end
+
+    node =
+      cond do
+        match?(%Obj{}, struct_root) and Obj.has?(struct_root, fn_name) ->
+          Obj.get(struct_root, fn_name)
+
+        match?(%Obj{}, provider) and Obj.has?(provider, fn_name) ->
+          Obj.get(provider, fn_name)
+
+        true ->
+          nil
+      end
+
+    if node == nil, do: raise("Unknown function: #{fn_name}")
+    node
+  end
+
+  # A group bag is an object with a `set` list.
+  defp is_group_bag(%Obj{} = v), do: is_list(Obj.get(v, "set"))
+  defp is_group_bag(_), do: false
+
+  # A function node has at least one child group bag.
+  defp has_groups(%Obj{} = v) do
+    Enum.any?(Obj.keys(v), fn k -> k != "name" and is_group_bag(Obj.get(v, k)) end)
+  end
+
+  defp has_groups(_), do: false
+
+  # ---------------------------------------------------------------------------
+  # Normalization (PROVIDER.md §2-4)
+  # ---------------------------------------------------------------------------
+
+  defp normalize(fn_name, group, index, raw) do
+    %{
+      function: fn_name,
+      group: group,
+      index: index,
+      id: opt_string(raw, "id"),
+      doc: obj_get(raw, "doc") == true,
+      client: opt_string(raw, "client"),
+      input: resolve_input(raw),
+      expect: resolve_expect(raw),
+      raw: raw
+    }
+  end
+
+  # str(raw[key]) if present and not null/nil, else nil (mirrors `!= null` in TS).
+  defp opt_string(raw, key) do
+    v = obj_get(raw, key)
+    if v == nil or v == :null, do: nil, else: stringify(v)
+  end
+
+  defp obj_has(%Obj{} = o, k), do: Obj.has?(o, k)
+  defp obj_has(_, _), do: false
+
+  defp obj_get(%Obj{} = o, k), do: Obj.get(o, k)
+  defp obj_get(_, _), do: nil
+
+  # §3 Input: precedence ctx > args > in. Absent "in" key => :null.
+  defp resolve_input(raw) do
+    cond do
+      obj_has(raw, "ctx") -> %{kind: :ctx, ctx: obj_get(raw, "ctx")}
+      obj_has(raw, "args") -> %{kind: :args, args: obj_get(raw, "args")}
+      true -> %{kind: :in, in: if(obj_has(raw, "in"), do: obj_get(raw, "in"), else: :null)}
+    end
+  end
+
+  defp parse_err(err) do
+    cond do
+      err == true ->
+        %{any: true, text: nil, regex: false}
+
+      is_binary(err) ->
+        case Regex.run(~r{^/(.+)/$}, err) do
+          [_, inner] -> %{any: false, text: inner, regex: true}
+          nil -> %{any: false, text: err, regex: false}
+        end
+
+      true ->
+        # Non-true, non-string err spec: treat as "any error".
+        %{any: true, text: nil, regex: false}
+    end
+  end
+
+  # §4 Expect: precedence err > out > match > absent. "out" present (even :null)
+  # => :value, decided by KEY PRESENCE not truthiness. Attach match whenever a
+  # "match" key exists.
+  defp resolve_expect(raw) do
+    match_part = if obj_has(raw, "match"), do: obj_get(raw, "match"), else: nil
+
+    cond do
+      obj_has(raw, "err") ->
+        %{kind: :error, error: parse_err(obj_get(raw, "err")), match: match_part}
+
+      obj_has(raw, "out") ->
+        %{kind: :value, value: obj_get(raw, "out"), match: match_part}
+
+      obj_has(raw, "match") ->
+        %{kind: :match, match: obj_get(raw, "match")}
+
+      true ->
+        %{kind: :absent}
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Pure comparison helpers (PROVIDER.md §5)
+  # ---------------------------------------------------------------------------
+
+  # stringify(x) = x if it's already a string, else compact JSON.
+  def stringify(x) when is_binary(x), do: x
+  def stringify(x), do: encode_json(x)
+
+  # Collapse __NULL__ / :null / nil to a single canonical null (:null) for
+  # lenient (flags.null == true) deep equality.
+  defp norm_null(@nullmark), do: :null
+  defp norm_null(nil), do: :null
+  defp norm_null(:null), do: :null
+  defp norm_null(x) when is_list(x), do: Enum.map(x, &norm_null/1)
+
+  defp norm_null(%Obj{} = o) do
+    Obj.new(Enum.map(Obj.keys(o), fn k -> {k, norm_null(Obj.get(o, k))} end))
+  end
+
+  defp norm_null(x), do: x
+
+  # Strict variant for {null: false} functions: only __NULL__ collapses to null;
+  # an absent value (nil) stays distinct from JSON null (:null).
+  defp norm_mark(@nullmark), do: :null
+  defp norm_mark(x) when is_list(x), do: Enum.map(x, &norm_mark/1)
+
+  defp norm_mark(%Obj{} = o) do
+    Obj.new(Enum.map(Obj.keys(o), fn k -> {k, norm_mark(Obj.get(o, k))} end))
+  end
+
+  defp norm_mark(x), do: x
+
+  @doc """
+  Scalar primitive match (matchval): `check == base`; else if `check` is a
+  string, "/re/" => regex test on stringify(base), otherwise case-insensitive
+  substring; else if `check` is a function => true.
+  """
+  def matchval(check, base) do
+    cond do
+      check === base ->
+        true
+
+      is_binary(check) ->
+        basestr = stringify(base)
+
+        case Regex.run(~r{^/(.+)/$}, check) do
+          [_, inner] ->
+            Regex.match?(Regex.compile!(inner), basestr)
+
+          nil ->
+            String.contains?(String.downcase(basestr), String.downcase(check))
+        end
+
+      is_function(check) ->
+        true
+
+      true ->
+        false
+    end
+  end
+
+  @doc "Deep equality with null/absent collapsed (runner default null:true)."
+  def equal(expected, actual) do
+    deep_eq(norm_null(expected), norm_null(actual))
+  end
+
+  @doc "Deep equality where absent (nil) is distinct from null (runner null:false)."
+  def equal_strict(expected, actual) do
+    deep_eq(norm_mark(expected), norm_mark(actual))
+  end
+
+  defp deep_eq(a, b) do
+    cond do
+      # Guard against any accidental bool/number coercion; mirror JS ===.
+      is_boolean(a) or is_boolean(b) ->
+        a === b
+
+      a === b ->
+        true
+
+      is_list(a) and is_list(b) ->
+        length(a) == length(b) and
+          a |> Enum.zip(b) |> Enum.all?(fn {x, y} -> deep_eq(x, y) end)
+
+      match?(%Obj{}, a) and match?(%Obj{}, b) ->
+        ak = Obj.keys(a)
+        bk = Obj.keys(b)
+
+        length(ak) == length(bk) and
+          Enum.all?(ak, fn k -> Obj.has?(b, k) and deep_eq(Obj.get(a, k), Obj.get(b, k)) end)
+
+      is_list(a) or is_list(b) ->
+        false
+
+      match?(%Obj{}, a) or match?(%Obj{}, b) ->
+        false
+
+      true ->
+        a == b
+    end
+  end
+
+  @doc "ErrorCheck vs a thrown message."
+  def error_matches(%{any: true}, _message), do: true
+
+  def error_matches(%{text: nil}, _message), do: false
+
+  def error_matches(%{text: text, regex: regex}, message) do
+    if regex do
+      Regex.match?(Regex.compile!(text), message)
+    else
+      String.contains?(String.downcase(message), String.downcase(text))
+    end
+  end
+
+  @doc """
+  Partial structural match: every leaf of `check` must match `base` at its
+  path. Returns %{ok: bool, path?, expected?, actual?}. First failure wins.
+  """
+  def struct_match(check, base) do
+    walk_leaves(check, [], %{ok: true}, fn val, path, result ->
+      if not result.ok do
+        result
+      else
+        baseval = getpath(base, path)
+
+        cond do
+          baseval != @missing and deep_eq_leaf(baseval, val) ->
+            result
+
+          val == @undefmark and baseval == @missing ->
+            result
+
+          val == @existsmark and baseval != @missing and baseval != :null ->
+            result
+
+          true ->
+            compare_base = if baseval == @missing, do: :null, else: baseval
+
+            if matchval(val, compare_base) do
+              result
+            else
+              %{ok: false, path: path, expected: val, actual: compare_base}
+            end
+        end
+      end
+    end)
+  end
+
+  # Leaf-level equality used inside struct_match (scalars; :null tolerant).
+  defp deep_eq_leaf(a, b), do: a === b
+
+  defp walk_leaves(node, path, acc, fun) when is_list(node) do
+    node
+    |> Enum.with_index()
+    |> Enum.reduce(acc, fn {v, i}, a ->
+      walk_leaves(v, path ++ [Integer.to_string(i)], a, fun)
+    end)
+  end
+
+  defp walk_leaves(%Obj{} = node, path, acc, fun) do
+    Enum.reduce(Obj.keys(node), acc, fn k, a ->
+      walk_leaves(Obj.get(node, k), path ++ [k], a, fun)
+    end)
+  end
+
+  defp walk_leaves(leaf, path, acc, fun), do: fun.(leaf, path, acc)
+
+  # getpath over the ordered representation; returns @missing when absent.
+  defp getpath(store, path) do
+    Enum.reduce_while(path, store, fn key, cur ->
+      cond do
+        cur == nil or cur == :null or cur == @missing ->
+          {:halt, @missing}
+
+        is_list(cur) ->
+          idx = String.to_integer(key)
+
+          if idx >= 0 and idx < length(cur) do
+            {:cont, Enum.at(cur, idx)}
+          else
+            {:halt, @missing}
+          end
+
+        match?(%Obj{}, cur) ->
+          if Obj.has?(cur, key), do: {:cont, Obj.get(cur, key)}, else: {:halt, @missing}
+
+        true ->
+          {:halt, @missing}
+      end
+    end)
+  end
+
+  # ---------------------------------------------------------------------------
+  # Minimal JSON encoder (compact) — for stringify / matchval.
+  # ---------------------------------------------------------------------------
+
+  defp encode_json(:null), do: "null"
+  defp encode_json(nil), do: "null"
+  defp encode_json(true), do: "true"
+  defp encode_json(false), do: "false"
+  defp encode_json(n) when is_integer(n), do: Integer.to_string(n)
+
+  defp encode_json(n) when is_float(n) do
+    # Render integral floats without a trailing ".0" to mirror JS JSON.stringify.
+    if Float.round(n) == n and abs(n) < 1.0e16 do
+      Integer.to_string(trunc(n))
+    else
+      Float.to_string(n)
+    end
+  end
+
+  defp encode_json(s) when is_binary(s), do: encode_string(s)
+
+  defp encode_json(l) when is_list(l) do
+    "[" <> (l |> Enum.map(&encode_json/1) |> Enum.join(",")) <> "]"
+  end
+
+  defp encode_json(%Obj{} = o) do
+    body =
+      Obj.keys(o)
+      |> Enum.map(fn k -> encode_string(k) <> ":" <> encode_json(Obj.get(o, k)) end)
+      |> Enum.join(",")
+
+    "{" <> body <> "}"
+  end
+
+  defp encode_json(f) when is_function(f), do: "null"
+
+  defp encode_string(s) do
+    inner =
+      s
+      |> String.to_charlist()
+      |> Enum.map(&escape_char/1)
+      |> IO.iodata_to_binary()
+
+    "\"" <> inner <> "\""
+  end
+
+  defp escape_char(?"), do: "\\\""
+  defp escape_char(?\\), do: "\\\\"
+  defp escape_char(?\n), do: "\\n"
+  defp escape_char(?\r), do: "\\r"
+  defp escape_char(?\t), do: "\\t"
+  defp escape_char(8), do: "\\b"
+  defp escape_char(12), do: "\\f"
+  defp escape_char(c) when c < 0x20, do: "\\u" <> pad4(Integer.to_string(c, 16))
+  defp escape_char(c), do: <<c::utf8>>
+
+  defp pad4(hex), do: String.pad_leading(String.downcase(hex), 4, "0")
+
+  # ---------------------------------------------------------------------------
+  # Minimal JSON parser (pure Elixir). Objects -> Obj, arrays -> list, strings
+  # -> binary, numbers -> integer|float, booleans -> true|false, null -> :null.
+  # ---------------------------------------------------------------------------
+
+  defp parse_json(str) do
+    {v, rest} = parse_value(str)
+
+    case skip_ws(rest) do
+      "" -> v
+      _ -> v
+    end
+  end
+
+  defp skip_ws(<<c, rest::binary>>) when c in [?\s, ?\t, ?\n, ?\r], do: skip_ws(rest)
+  defp skip_ws(s), do: s
+
+  defp parse_value(s) do
+    s = skip_ws(s)
+
+    case s do
+      "{" <> rest -> parse_object(rest, [])
+      "[" <> rest -> parse_array(rest, [])
+      "\"" <> rest -> parse_string_raw(rest, [])
+      "true" <> rest -> {true, rest}
+      "false" <> rest -> {false, rest}
+      "null" <> rest -> {:null, rest}
+      _ -> parse_number(s)
+    end
+  end
+
+  defp parse_object(s, acc) do
+    s = skip_ws(s)
+
+    case s do
+      "}" <> rest ->
+        {Obj.new(Enum.reverse(acc)), rest}
+
+      _ ->
+        "\"" <> s1 = s
+        {key, s2} = parse_string_raw(s1, [])
+        s3 = skip_ws(s2)
+        ":" <> s4 = s3
+        {val, s5} = parse_value(s4)
+        s6 = skip_ws(s5)
+
+        case s6 do
+          "," <> r -> parse_object(r, [{key, val} | acc])
+          "}" <> r -> parse_object("}" <> r, [{key, val} | acc])
+        end
+    end
+  end
+
+  defp parse_array(s, acc) do
+    s = skip_ws(s)
+
+    case s do
+      "]" <> rest ->
+        {Enum.reverse(acc), rest}
+
+      _ ->
+        {val, s1} = parse_value(s)
+        s2 = skip_ws(s1)
+
+        case s2 do
+          "," <> r -> parse_array(r, [val | acc])
+          "]" <> r -> parse_array("]" <> r, [val | acc])
+        end
+    end
+  end
+
+  defp parse_string_raw("\"" <> rest, acc), do: {IO.iodata_to_binary(Enum.reverse(acc)), rest}
+
+  defp parse_string_raw("\\" <> <<c, rest::binary>>, acc) do
+    case c do
+      ?" -> parse_string_raw(rest, ["\"" | acc])
+      ?\\ -> parse_string_raw(rest, ["\\" | acc])
+      ?/ -> parse_string_raw(rest, ["/" | acc])
+      ?n -> parse_string_raw(rest, ["\n" | acc])
+      ?r -> parse_string_raw(rest, ["\r" | acc])
+      ?t -> parse_string_raw(rest, ["\t" | acc])
+      ?b -> parse_string_raw(rest, [<<8>> | acc])
+      ?f -> parse_string_raw(rest, [<<12>> | acc])
+      ?u ->
+        <<hex::binary-size(4), rest2::binary>> = rest
+        code = String.to_integer(hex, 16)
+        parse_string_raw(rest2, [<<code::utf8>> | acc])
+    end
+  end
+
+  defp parse_string_raw(<<c::utf8, rest::binary>>, acc),
+    do: parse_string_raw(rest, [<<c::utf8>> | acc])
+
+  defp parse_number(s) do
+    {numstr, rest} = take_number(s, [])
+    n = IO.iodata_to_binary(Enum.reverse(numstr))
+
+    val =
+      if String.contains?(n, ".") or String.contains?(n, "e") or String.contains?(n, "E") do
+        {f, ""} = Float.parse(n)
+        f
+      else
+        String.to_integer(n)
+      end
+
+    {val, rest}
+  end
+
+  defp take_number(<<c, rest::binary>>, acc)
+       when c in ?0..?9 or c in [?-, ?+, ?., ?e, ?E],
+       do: take_number(rest, [<<c>> | acc])
+
+  defp take_number(s, acc), do: {acc, s}
+end
diff --git a/test/proto/elixir/smoke.exs b/test/proto/elixir/smoke.exs
new file mode 100644
index 0000000..091a04d
--- /dev/null
+++ b/test/proto/elixir/smoke.exs
@@ -0,0 +1,72 @@
+# Smoke test for the Elixir test provider port. Prints summary stats that must
+# match the canonical TS output documented in PROVIDER.md / the task brief.
+#
+# Run (when Elixir is available):  elixir smoke.exs
+# This file deliberately uses NO JSON dependency (provider.ex ships its own).
+
+Code.require_file("provider.ex", __DIR__)
+
+defmodule Smoke do
+  alias Voxgig.Proto.Provider, as: P
+
+  def main do
+    prov = P.load()
+
+    fns = P.functions(prov)
+    IO.puts("functions: " <> Enum.join(fns, ", "))
+
+    {total, expect_kinds, input_kinds} =
+      Enum.reduce(fns, {0, %{}, %{}}, fn fn_name, {total, ek, ik} ->
+        Enum.reduce(P.entries(prov, fn_name), {total, ek, ik}, fn entry, {t, e, i} ->
+          ekind = entry.expect.kind
+          ikind = entry.input.kind
+          {t + 1, Map.update(e, ekind, 1, &(&1 + 1)), Map.update(i, ikind, 1, &(&1 + 1))}
+        end)
+      end)
+
+    IO.puts("total entries: #{total}")
+    IO.puts("expect kinds: " <> kindstr(expect_kinds))
+    IO.puts("input kinds: " <> kindstr(input_kinds))
+
+    e = hd(P.entries(prov, "getpath", "basic"))
+
+    IO.puts(
+      "getpath/basic[0]: " <>
+        "id=#{e.id}, doc=#{e.doc}, " <>
+        "input.kind=#{e.input.kind}, " <>
+        "expect.kind=#{e.expect.kind}, expect.value=#{fmt(e.expect.value)}"
+    )
+
+    # --- helper sanity checks ------------------------------------------------
+    IO.puts("equal(:null, nil) lenient: #{P.equal(:null, nil)}")
+
+    IO.puts(
+      "equal_strict distinguishes nil vs __NULL__-collapse: " <>
+        "#{P.equal_strict(nil, "__NULL__")} / #{P.equal_strict(:null, "__NULL__")}"
+    )
+
+    IO.puts(
+      "error_matches substring case-insensitive: " <>
+        "#{P.error_matches(%{any: false, text: "Foo", regex: false}, "a foobar error")}"
+    )
+
+    a = P.Obj.new([{"a", P.Obj.new([{"b", 2}])}])
+    b = P.Obj.new([{"a", P.Obj.new([{"b", 3}])}])
+    IO.puts("struct_match failure: #{inspect(P.struct_match(a, b))}")
+  end
+
+  # Stable "k=v, k=v" rendering with keys sorted for deterministic output.
+  defp kindstr(map) do
+    map
+    |> Enum.map(fn {k, v} -> {Atom.to_string(k), v} end)
+    |> Enum.sort_by(fn {k, _} -> k end)
+    |> Enum.map(fn {k, v} -> "#{k}=#{v}" end)
+    |> Enum.join(", ")
+  end
+
+  defp fmt(:null), do: "null"
+  defp fmt(v) when is_binary(v), do: v
+  defp fmt(v), do: P.stringify(v)
+end
+
+Smoke.main()
diff --git a/test/proto/go/cmd/smoke/main.go b/test/proto/go/cmd/smoke/main.go
new file mode 100644
index 0000000..701d324
--- /dev/null
+++ b/test/proto/go/cmd/smoke/main.go
@@ -0,0 +1,48 @@
+// Smoke test for the Go test-provider port. Loads the default corpus and
+// prints summary numbers to verify parity with the canonical TS reference.
+package main
+
+import (
+	"fmt"
+	"strings"
+
+	provider "voxgig/structproto"
+)
+
+func main() {
+	p, err := provider.Load("")
+	if err != nil {
+		panic(err)
+	}
+
+	fns := p.Functions()
+	fmt.Println("functions:", strings.Join(fns, ", "))
+
+	total := 0
+	expectKinds := map[string]int{}
+	inputKinds := map[string]int{}
+	for _, fn := range fns {
+		for _, e := range p.Entries(fn) {
+			total++
+			expectKinds[e.Expect.Kind]++
+			inputKinds[e.Input.Kind]++
+		}
+	}
+
+	fmt.Println("total entries:", total)
+	fmt.Printf("expect kinds: value=%d, absent=%d, match=%d, error=%d\n",
+		expectKinds["value"], expectKinds["absent"], expectKinds["match"], expectKinds["error"])
+	fmt.Printf("input kinds: in=%d, args=%d, ctx=%d\n",
+		inputKinds["in"], inputKinds["args"], inputKinds["ctx"])
+
+	gp := p.Entries("getpath", "basic")
+	if len(gp) > 0 {
+		e := gp[0]
+		id := "<nil>"
+		if e.ID != nil {
+			id = *e.ID
+		}
+		fmt.Printf("getpath/basic[0]: id=%s, doc=%v, input.kind=%s, expect.kind=%s, expect.value=%v\n",
+			id, e.Doc, e.Input.Kind, e.Expect.Kind, e.Expect.Value)
+	}
+}
diff --git a/test/proto/go/go.mod b/test/proto/go/go.mod
new file mode 100644
index 0000000..06d9202
--- /dev/null
+++ b/test/proto/go/go.mod
@@ -0,0 +1,3 @@
+module voxgig/structproto
+
+go 1.24
diff --git a/test/proto/go/provider.go b/test/proto/go/provider.go
new file mode 100644
index 0000000..a08952c
--- /dev/null
+++ b/test/proto/go/provider.go
@@ -0,0 +1,641 @@
+// Test Provider (prototype) — Go port of the canonical TypeScript
+// implementation (../ts/provider.ts).
+//
+// Reads the shared corpus (build/test/test.json) and hands test code clean,
+// normalized cases. It is NOT a test runner: it never calls the subject and
+// never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+//
+// Zero runtime dependencies (Go standard library only), matching repo policy.
+
+package provider
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"regexp"
+	"runtime"
+	"strconv"
+	"strings"
+)
+
+const (
+	nullMark   = "__NULL__"
+	undefMark  = "__UNDEF__"
+	existsMark = "__EXISTS__"
+)
+
+// Input is a tagged invocation: exactly one of in/args/ctx is meaningful,
+// selected by Kind (mirrors the runner's ctx → args → in precedence).
+type Input struct {
+	Kind string         // "in" | "args" | "ctx"
+	In   any            // Kind=="in"
+	Args []any          // Kind=="args"
+	Ctx  map[string]any // Kind=="ctx"
+}
+
+// ErrorCheck is the parsed form of a raw `err` spec.
+type ErrorCheck struct {
+	Any     bool
+	Text    string
+	HasText bool
+	Regex   bool
+}
+
+// Expect is a tagged expectation: value | error | match | absent.
+type Expect struct {
+	Kind     string // "value" | "error" | "match" | "absent"
+	Value    any    // Kind=="value"
+	HasValue bool   // distinguishes present-null from absent
+	Error    *ErrorCheck
+	Match    any // populated whenever a `match` key is present
+}
+
+// Entry is the normalized record for a single corpus test case.
+type Entry struct {
+	Function string
+	Group    string
+	Index    int
+	ID       *string
+	Doc      bool
+	Client   *string
+	Input    Input
+	Expect   Expect
+	Raw      map[string]any
+}
+
+// MatchResult is the outcome of a structural match.
+type MatchResult struct {
+	Ok       bool
+	Path     []string
+	Expected any
+	Actual   any
+}
+
+// TestProvider holds the parsed corpus.
+type TestProvider struct {
+	spec  any
+	order map[string][]string // object-path -> ordered keys (for stable listing)
+}
+
+// defaultTestFile resolves build/test/test.json relative to the repo root,
+// using the location of this source file so it works regardless of cwd.
+func defaultTestFile() string {
+	_, here, _, _ := runtime.Caller(0) // .../test/proto/go/provider.go
+	dir := filepath.Dir(here)          // test/proto/go
+	return filepath.Join(dir, "..", "..", "..", "build", "test", "test.json")
+}
+
+// Load parses test.json. An empty testfile means the default corpus path.
+func Load(testfile string) (*TestProvider, error) {
+	file := testfile
+	if file == "" {
+		file = defaultTestFile()
+	}
+	data, err := os.ReadFile(file) // #nosec G304 -- fixed test-corpus path.
+	if err != nil {
+		return nil, err
+	}
+	var spec any
+	if err := json.Unmarshal(data, &spec); err != nil {
+		return nil, err
+	}
+	order := map[string][]string{}
+	if err := recordOrder(data, order); err != nil {
+		return nil, err
+	}
+	return &TestProvider{spec: spec, order: order}, nil
+}
+
+// recordOrder walks the raw JSON with a streaming decoder, recording the key
+// order of every object keyed by its slash-joined path. encoding/json does not
+// preserve object key order, so this restores deterministic, corpus-faithful
+// ordering for Functions()/Groups().
+func recordOrder(data []byte, order map[string][]string) error {
+	dec := json.NewDecoder(bytes.NewReader(data))
+	dec.UseNumber()
+	return scanValue(dec, "", order)
+}
+
+func scanValue(dec *json.Decoder, path string, order map[string][]string) error {
+	tok, err := dec.Token()
+	if err != nil {
+		return err
+	}
+	delim, ok := tok.(json.Delim)
+	if !ok {
+		return nil // scalar
+	}
+	switch delim {
+	case '{':
+		var keys []string
+		for dec.More() {
+			kt, err := dec.Token()
+			if err != nil {
+				return err
+			}
+			key := kt.(string)
+			keys = append(keys, key)
+			child := path + "/" + key
+			if path == "" {
+				child = key
+			}
+			if err := scanValue(dec, child, order); err != nil {
+				return err
+			}
+		}
+		order[path] = keys
+		_, err := dec.Token() // consume '}'
+		return err
+	case '[':
+		i := 0
+		for dec.More() {
+			child := path + "/" + strconv.Itoa(i)
+			if err := scanValue(dec, child, order); err != nil {
+				return err
+			}
+			i++
+		}
+		_, err := dec.Token() // consume ']'
+		return err
+	}
+	return nil
+}
+
+// Raw returns the parsed test.json (escape hatch).
+func (p *TestProvider) Raw() any {
+	return p.spec
+}
+
+// root returns spec.struct if present, else spec itself, as a map.
+func (p *TestProvider) root() map[string]any {
+	if m, ok := p.spec.(map[string]any); ok {
+		if s, ok := m["struct"].(map[string]any); ok {
+			return s
+		}
+		return m
+	}
+	return nil
+}
+
+// fnNode resolves the node for a function (under struct, falling back to root).
+func (p *TestProvider) fnNode(fn string) map[string]any {
+	if m, ok := p.spec.(map[string]any); ok {
+		if s, ok := m["struct"].(map[string]any); ok {
+			if n, ok := s[fn].(map[string]any); ok {
+				return n
+			}
+		}
+		if n, ok := m[fn].(map[string]any); ok {
+			return n
+		}
+	}
+	return nil
+}
+
+// rootPath returns the order-table path prefix for the function-bearing root
+// ("struct" if present, else "").
+func (p *TestProvider) rootPath() string {
+	if m, ok := p.spec.(map[string]any); ok {
+		if _, ok := m["struct"].(map[string]any); ok {
+			return "struct"
+		}
+	}
+	return ""
+}
+
+// Functions lists the function names in corpus order.
+func (p *TestProvider) Functions() []string {
+	root := p.root()
+	if root == nil {
+		return nil
+	}
+	out := []string{}
+	for _, k := range p.orderedKeys(p.rootPath(), root) {
+		if isGroupBag(root[k]) || hasGroups(root[k]) {
+			out = append(out, k)
+		}
+	}
+	return out
+}
+
+// Groups lists the group names for a function in corpus order.
+func (p *TestProvider) Groups(fn string) []string {
+	node := p.fnNode(fn)
+	if node == nil {
+		return nil
+	}
+	rp := p.rootPath()
+	fnPath := fn
+	if rp != "" {
+		fnPath = rp + "/" + fn
+	}
+	out := []string{}
+	for _, k := range p.orderedKeys(fnPath, node) {
+		if k != "name" && isGroupBag(node[k]) {
+			out = append(out, k)
+		}
+	}
+	return out
+}
+
+// orderedKeys returns the keys of node m in corpus order if known, else in map
+// iteration order (which is acceptable for callers that only need the set).
+func (p *TestProvider) orderedKeys(path string, m map[string]any) []string {
+	if ord, ok := p.order[path]; ok {
+		return ord
+	}
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	return keys
+}
+
+// Entries returns all entries for a function, or for one specific group.
+func (p *TestProvider) Entries(fn string, group ...string) []Entry {
+	node := p.fnNode(fn)
+	if node == nil {
+		return nil
+	}
+	var groups []string
+	if len(group) > 0 {
+		groups = []string{group[0]}
+	} else {
+		groups = p.Groups(fn)
+	}
+	out := []Entry{}
+	for _, g := range groups {
+		bag, ok := node[g].(map[string]any)
+		if !ok || !isGroupBag(bag) {
+			continue
+		}
+		set, _ := bag["set"].([]any)
+		for i, raw := range set {
+			rawMap, _ := raw.(map[string]any)
+			out = append(out, normalize(fn, g, i, rawMap))
+		}
+	}
+	return out
+}
+
+// isGroupBag reports whether v is a map containing a `set` array.
+func isGroupBag(v any) bool {
+	m, ok := v.(map[string]any)
+	if !ok {
+		return false
+	}
+	_, ok = m["set"].([]any)
+	return ok
+}
+
+// hasGroups reports whether v is a map with at least one child group bag.
+func hasGroups(v any) bool {
+	m, ok := v.(map[string]any)
+	if !ok {
+		return false
+	}
+	for k, cv := range m {
+		if k != "name" && isGroupBag(cv) {
+			return true
+		}
+	}
+	return false
+}
+
+func has(m map[string]any, key string) bool {
+	if m == nil {
+		return false
+	}
+	_, ok := m[key]
+	return ok
+}
+
+func normalize(fn, group string, index int, raw map[string]any) Entry {
+	var id *string
+	if v, ok := raw["id"]; ok && v != nil {
+		s := stringify(v)
+		id = &s
+	}
+	var client *string
+	if v, ok := raw["client"]; ok && v != nil {
+		s := stringify(v)
+		client = &s
+	}
+	doc := raw["doc"] == true
+	return Entry{
+		Function: fn,
+		Group:    group,
+		Index:    index,
+		ID:       id,
+		Doc:      doc,
+		Client:   client,
+		Input:    resolveInput(raw),
+		Expect:   resolveExpect(raw),
+		Raw:      raw,
+	}
+}
+
+func resolveInput(raw map[string]any) Input {
+	if has(raw, "ctx") {
+		ctx, _ := raw["ctx"].(map[string]any)
+		return Input{Kind: "ctx", Ctx: ctx}
+	}
+	if has(raw, "args") {
+		args, _ := raw["args"].([]any)
+		return Input{Kind: "args", Args: args}
+	}
+	if has(raw, "in") {
+		return Input{Kind: "in", In: raw["in"]}
+	}
+	return Input{Kind: "in", In: nil}
+}
+
+func parseErr(err any) ErrorCheck {
+	if err == true {
+		return ErrorCheck{Any: true}
+	}
+	if s, ok := err.(string); ok {
+		if m := reErr.FindStringSubmatch(s); m != nil {
+			return ErrorCheck{Text: m[1], HasText: true, Regex: true}
+		}
+		return ErrorCheck{Text: s, HasText: true}
+	}
+	// Non-true, non-string err spec: treat as "any error".
+	return ErrorCheck{Any: true}
+}
+
+var reErr = regexp.MustCompile(`^/(.+)/$`)
+
+func resolveExpect(raw map[string]any) Expect {
+	var matchPart any
+	hasMatch := has(raw, "match")
+	if hasMatch {
+		matchPart = raw["match"]
+	}
+	if has(raw, "err") {
+		ec := parseErr(raw["err"])
+		return Expect{Kind: "error", Error: &ec, Match: matchPart}
+	}
+	if has(raw, "out") {
+		return Expect{Kind: "value", Value: raw["out"], HasValue: true, Match: matchPart}
+	}
+	if hasMatch {
+		return Expect{Kind: "match", Match: matchPart}
+	}
+	return Expect{Kind: "absent"}
+}
+
+// ─── pure comparison helpers ───────────────────────────────────────────────
+
+func stringify(x any) string {
+	if s, ok := x.(string); ok {
+		return s
+	}
+	b, err := json.Marshal(x)
+	if err != nil {
+		return ""
+	}
+	return string(b)
+}
+
+// Matchval reproduces the runner's scalar match: deep-equal, then string rules.
+func Matchval(check, base any) bool {
+	if EqualStrict(check, base) {
+		return true
+	}
+	if cs, ok := check.(string); ok {
+		basestr := stringify(base)
+		if m := reErr.FindStringSubmatch(cs); m != nil {
+			re, err := regexp.Compile(m[1])
+			if err != nil {
+				return false
+			}
+			return re.MatchString(basestr)
+		}
+		return strings.Contains(strings.ToLower(basestr), strings.ToLower(cs))
+	}
+	return false
+}
+
+// Equal is deep equality collapsing "__NULL__" and nil to nil on both sides.
+func Equal(expected, actual any) bool {
+	return deepEq(normNull(expected), normNull(actual))
+}
+
+// EqualStrict is deep equality normalizing only "__NULL__" to nil.
+func EqualStrict(expected, actual any) bool {
+	return deepEq(normMark(expected), normMark(actual))
+}
+
+func normNull(x any) any {
+	if x == nullMark || x == nil {
+		return nil
+	}
+	switch v := x.(type) {
+	case []any:
+		out := make([]any, len(v))
+		for i, e := range v {
+			out[i] = normNull(e)
+		}
+		return out
+	case map[string]any:
+		out := make(map[string]any, len(v))
+		for k, e := range v {
+			out[k] = normNull(e)
+		}
+		return out
+	}
+	return x
+}
+
+func normMark(x any) any {
+	if x == nullMark {
+		return nil
+	}
+	switch v := x.(type) {
+	case []any:
+		out := make([]any, len(v))
+		for i, e := range v {
+			out[i] = normMark(e)
+		}
+		return out
+	case map[string]any:
+		out := make(map[string]any, len(v))
+		for k, e := range v {
+			out[k] = normMark(e)
+		}
+		return out
+	}
+	return x
+}
+
+func deepEq(a, b any) bool {
+	if scalarEq(a, b) {
+		return true
+	}
+	al, aok := a.([]any)
+	bl, bok := b.([]any)
+	if aok && bok {
+		if len(al) != len(bl) {
+			return false
+		}
+		for i := range al {
+			if !deepEq(al[i], bl[i]) {
+				return false
+			}
+		}
+		return true
+	}
+	am, aok := a.(map[string]any)
+	bm, bok := b.(map[string]any)
+	if aok && bok {
+		if len(am) != len(bm) {
+			return false
+		}
+		for k, av := range am {
+			bv, ok := bm[k]
+			if !ok || !deepEq(av, bv) {
+				return false
+			}
+		}
+		return true
+	}
+	return false
+}
+
+// scalarEq compares scalars; JSON numbers are float64 so numeric values compare
+// directly. nil==nil is true here.
+func scalarEq(a, b any) bool {
+	if a == nil && b == nil {
+		return true
+	}
+	if a == nil || b == nil {
+		return false
+	}
+	af, aok := toFloat(a)
+	bf, bok := toFloat(b)
+	if aok && bok {
+		return af == bf
+	}
+	if aok != bok {
+		return false
+	}
+	switch av := a.(type) {
+	case string:
+		bv, ok := b.(string)
+		return ok && av == bv
+	case bool:
+		bv, ok := b.(bool)
+		return ok && av == bv
+	}
+	return false
+}
+
+func toFloat(x any) (float64, bool) {
+	switch v := x.(type) {
+	case float64:
+		return v, true
+	case float32:
+		return float64(v), true
+	case int:
+		return float64(v), true
+	case int64:
+		return float64(v), true
+	}
+	return 0, false
+}
+
+// ErrorMatches checks an ErrorCheck against a thrown message.
+func ErrorMatches(check ErrorCheck, message string) bool {
+	if check.Any {
+		return true
+	}
+	if !check.HasText {
+		return false
+	}
+	if check.Regex {
+		re, err := regexp.Compile(check.Text)
+		if err != nil {
+			return false
+		}
+		return re.MatchString(message)
+	}
+	return strings.Contains(strings.ToLower(message), strings.ToLower(check.Text))
+}
+
+// StructMatch performs a partial structural match: every leaf of check must
+// match base at its path.
+func StructMatch(check, base any) MatchResult {
+	result := MatchResult{Ok: true}
+	walkLeaves(check, nil, func(val any, path []string) {
+		if !result.Ok {
+			return
+		}
+		baseval, found := getpath(base, path)
+		if found && scalarEq(baseval, val) {
+			return
+		}
+		if val == undefMark && (!found || baseval == nil) {
+			return
+		}
+		if val == existsMark && found && baseval != nil {
+			return
+		}
+		if !Matchval(val, baseval) {
+			result = MatchResult{Ok: false, Path: path, Expected: val, Actual: baseval}
+		}
+	})
+	return result
+}
+
+func walkLeaves(node any, path []string, fn func(val any, path []string)) {
+	switch v := node.(type) {
+	case []any:
+		for i, e := range v {
+			walkLeaves(e, appendPath(path, strconv.Itoa(i)), fn)
+		}
+	case map[string]any:
+		for k, e := range v {
+			walkLeaves(e, appendPath(path, k), fn)
+		}
+	default:
+		fn(node, path)
+	}
+}
+
+func appendPath(path []string, key string) []string {
+	out := make([]string, len(path)+1)
+	copy(out, path)
+	out[len(path)] = key
+	return out
+}
+
+// getpath descends store following path. The bool reports whether the leaf was
+// present (false means it ran off a nil or a missing key).
+func getpath(store any, path []string) (any, bool) {
+	cur := store
+	for _, key := range path {
+		if cur == nil {
+			return nil, false
+		}
+		switch c := cur.(type) {
+		case map[string]any:
+			v, ok := c[key]
+			if !ok {
+				return nil, false
+			}
+			cur = v
+		case []any:
+			idx, err := strconv.Atoi(key)
+			if err != nil || idx < 0 || idx >= len(c) {
+				return nil, false
+			}
+			cur = c[idx]
+		default:
+			return nil, false
+		}
+	}
+	return cur, true
+}
diff --git a/test/proto/haskell/Provider.hs b/test/proto/haskell/Provider.hs
new file mode 100644
index 0000000..861212e
--- /dev/null
+++ b/test/proto/haskell/Provider.hs
@@ -0,0 +1,532 @@
+-- Test Provider (prototype) — Haskell port of the canonical ts/provider.ts.
+--
+-- Reads the shared corpus (build/test/test.json) and hands test code clean,
+-- normalized cases. It is NOT a test runner: it never calls the subject and
+-- never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+--
+-- DEPENDENCY-FREE: GHC base only. The JSON reader is self-contained (adapted
+-- from haskell/test/Runner.hs), producing an order-preserving `Json` type
+-- whose objects are association lists.
+--
+-- NOTE: GHC is unavailable in this environment, so this file has NOT been
+-- compiled or executed. It is a faithful port written from the canonical
+-- TypeScript source and the PROVIDER.md spec.
+
+{-# LANGUAGE LambdaCase #-}
+
+module Provider
+  ( Json(..)
+  , Provider
+  , Entry(..)
+  , Input(..)
+  , InputKind(..)
+  , Expect(..)
+  , ExpectKind(..)
+  , ErrorCheck(..)
+  , MatchResult(..)
+  , parseJson
+  , load
+  , raw
+  , functions
+  , groups
+  , entries
+  , stringify
+  , matchval
+  , equal
+  , equalStrict
+  , structMatch
+  , errorMatches
+  ) where
+
+import Data.Char (chr, toLower)
+import Data.IORef
+import Data.List (isInfixOf)
+import Numeric (readHex, showHex)
+import System.IO.Unsafe (unsafePerformIO)
+
+-- ─── JSON model ─────────────────────────────────────────────────────────────
+-- JObj is an association list to preserve key order (mirrors JSON.parse order
+-- preservation and the runner's order-preserving maps).
+
+data Json
+  = JNull
+  | JBool Bool
+  | JNum Double
+  | JStr String
+  | JArr [Json]
+  | JObj [(String, Json)]
+  deriving (Show)
+
+-- Reference equality for the model: structural, order-insensitive for objects
+-- (object equality compares by key membership, matching deepEq in the canon).
+instance Eq Json where
+  JNull        == JNull        = True
+  (JBool a)    == (JBool b)    = a == b
+  (JNum a)     == (JNum b)     = a == b
+  (JStr a)     == (JStr b)     = a == b
+  (JArr a)     == (JArr b)     = length a == length b && and (zipWith (==) a b)
+  (JObj a)     == (JObj b)     =
+    length a == length b
+      && all (\(k, v) -> case lookup k b of Just w -> v == w; Nothing -> False) a
+  _            == _            = False
+
+-- ─── Sentinels ──────────────────────────────────────────────────────────────
+
+nullmark, undefmark, existsmark :: String
+nullmark = "__NULL__"
+undefmark = "__UNDEF__"
+existsmark = "__EXISTS__"
+
+-- ─── JSON parser ────────────────────────────────────────────────────────────
+-- Adapted from haskell/test/Runner.hs's IORef-backed reader, retargeted at the
+-- pure order-preserving `Json` type. Handles escapes/\uXXXX, numbers,
+-- true/false/null. Uses an IORef cursor over the input held in unsafePerformIO
+-- so the public surface stays pure.
+
+parseJson :: String -> Json
+parseJson s0 = unsafePerformIO (jsonRead s0)
+{-# NOINLINE parseJson #-}
+
+jsonRead :: String -> IO Json
+jsonRead s0 = do
+  posRef <- newIORef 0
+  let arr = s0
+      n = length arr
+      at i = arr !! i
+      peek = do p <- readIORef posRef; return (if p < n then Just (at p) else Nothing)
+      adv = modifyIORef' posRef (+ 1)
+      skipWs = do
+        p <- readIORef posRef
+        if p < n && (at p `elem` " \t\n\r") then adv >> skipWs else return ()
+      pval = do
+        skipWs
+        mc <- peek
+        case mc of
+          Just '{' -> pobj
+          Just '[' -> parr
+          Just '"' -> JStr <$> pstr
+          Just 't' -> modifyIORef' posRef (+ 4) >> return (JBool True)
+          Just 'f' -> modifyIORef' posRef (+ 5) >> return (JBool False)
+          Just 'n' -> modifyIORef' posRef (+ 4) >> return JNull
+          _        -> pnum
+      pobj = do
+        adv; skipWs
+        mc <- peek
+        if mc == Just '}' then adv >> return (JObj [])
+        else do
+          accRef <- newIORef []
+          let loop = do
+                skipWs
+                k <- pstr
+                skipWs; adv  -- ':'
+                v <- pval
+                modifyIORef' accRef ((k, v) :)
+                skipWs
+                c <- peek >>= \case Just ch -> adv >> return ch; Nothing -> return '}'
+                if c == ',' then loop
+                else do acc <- readIORef accRef; return (JObj (reverse acc))
+          loop
+      parr = do
+        adv; skipWs
+        mc <- peek
+        if mc == Just ']' then adv >> return (JArr [])
+        else do
+          accRef <- newIORef []
+          let loop = do
+                v <- pval
+                modifyIORef' accRef (v :)
+                skipWs
+                c <- peek >>= \case Just ch -> adv >> return ch; Nothing -> return ']'
+                if c == ',' then loop
+                else do acc <- readIORef accRef; return (JArr (reverse acc))
+          loop
+      pstr = do
+        adv  -- opening quote
+        bRef <- newIORef []
+        let push c = modifyIORef' bRef (c :)
+            loop = do
+              p <- readIORef posRef
+              let c = at p
+              adv
+              if c == '"' then do b <- readIORef bRef; return (reverse b)
+              else if c == '\\' then do
+                p2 <- readIORef posRef
+                let e = at p2
+                adv
+                case e of
+                  '"'  -> push '"' >> loop
+                  '\\' -> push '\\' >> loop
+                  '/'  -> push '/' >> loop
+                  'n'  -> push '\n' >> loop
+                  't'  -> push '\t' >> loop
+                  'r'  -> push '\r' >> loop
+                  'b'  -> push '\b' >> loop
+                  'f'  -> push '\f' >> loop
+                  'u'  -> do
+                    pp <- readIORef posRef
+                    let hex = take 4 (drop pp arr)
+                    modifyIORef' posRef (+ 4)
+                    case readHex hex of
+                      [(code, _)] -> push (chr code) >> loop
+                      _           -> loop
+                  _    -> push e >> loop
+              else push c >> loop
+        loop
+      pnum = do
+        start <- readIORef posRef
+        let go = do
+              p <- readIORef posRef
+              if p < n && (at p `elem` "0123456789-+.eE") then adv >> go else return ()
+        go
+        end <- readIORef posRef
+        let tok = take (end - start) (drop start arr)
+        return (JNum (read tok))
+  pval
+
+-- ─── Provider ───────────────────────────────────────────────────────────────
+
+newtype Provider = Provider { spec :: Json }
+
+-- Default corpus path: build/test/test.json relative to the repo root.
+-- This file lives at test/proto/haskell, so the repo root is three levels up.
+defaultTestFile :: FilePath
+defaultTestFile = "../../../build/test/test.json"
+
+load :: Maybe FilePath -> IO Provider
+load mfile = do
+  let file = maybe defaultTestFile id mfile
+  contents <- readFile file
+  parsed <- jsonRead contents
+  return (Provider parsed)
+
+raw :: Provider -> Json
+raw = spec
+
+-- The root used for function discovery: spec.struct if present, else spec.
+specRoot :: Provider -> Json
+specRoot p = case objLookup (spec p) "struct" of
+  Just node -> node
+  Nothing   -> spec p
+
+fnNode :: Provider -> String -> Json
+fnNode p fn =
+  case objLookup (spec p) "struct" >>= \root -> objLookup root fn of
+    Just node -> node
+    Nothing   -> case objLookup (spec p) fn of
+      Just node -> node
+      Nothing   -> error ("Unknown function: " ++ fn)
+
+functions :: Provider -> [String]
+functions p =
+  case specRoot p of
+    JObj kvs -> [k | (k, v) <- kvs, isGroupBag v || hasGroups v]
+    _        -> []
+
+groups :: Provider -> String -> [String]
+groups p fn =
+  case fnNode p fn of
+    JObj kvs -> [k | (k, v) <- kvs, k /= "name", isGroupBag v]
+    _        -> []
+
+entries :: Provider -> String -> Maybe String -> [Entry]
+entries p fn mgroup =
+  let node = fnNode p fn
+      gs = maybe (groups p fn) (: []) mgroup
+      collect g =
+        case objLookup node g of
+          Just bag | isGroupBag bag ->
+            case objLookup bag "set" of
+              Just (JArr items) -> zipWith (normalize fn g) [0 ..] items
+              _                 -> []
+          _ -> []
+  in concatMap collect gs
+
+-- A group bag is an object with a `set` array.
+isGroupBag :: Json -> Bool
+isGroupBag v = case v of
+  JObj kvs -> case lookup "set" kvs of Just (JArr _) -> True; _ -> False
+  _        -> False
+
+-- A function node has at least one child group bag.
+hasGroups :: Json -> Bool
+hasGroups v = case v of
+  JObj kvs -> any (\(k, x) -> k /= "name" && isGroupBag x) kvs
+  _        -> False
+
+-- ─── Entry model ────────────────────────────────────────────────────────────
+
+data InputKind = KIn | KArgs | KCtx deriving (Eq, Show)
+
+data Input = Input
+  { ikind  :: InputKind
+  , ivalue :: Json
+  } deriving (Show)
+
+data ExpectKind = EValue | EError | EMatch | EAbsent deriving (Eq, Show)
+
+data ErrorCheck = ErrorCheck
+  { anyErr :: Bool
+  , etext  :: Maybe String
+  , eregex :: Bool
+  } deriving (Show)
+
+data Expect = Expect
+  { ekind  :: ExpectKind
+  , evalue :: Maybe Json
+  , eerror :: Maybe ErrorCheck
+  , ematch :: Maybe Json
+  } deriving (Show)
+
+data Entry = Entry
+  { function :: String
+  , group    :: String
+  , index    :: Int
+  , eid      :: Maybe String
+  , doc      :: Bool
+  , client   :: Maybe String
+  , input    :: Input
+  , expect   :: Expect
+  , eraw     :: Json
+  } deriving (Show)
+
+-- ─── Normalization (exactly per PROVIDER.md) ───────────────────────────────
+
+-- Object key lookup preserving order semantics; Nothing when key absent.
+objLookup :: Json -> String -> Maybe Json
+objLookup (JObj kvs) k = lookup k kvs
+objLookup _ _          = Nothing
+
+-- Key presence on an object (the assoc-list keys), NOT a null-check.
+objHas :: Json -> String -> Bool
+objHas (JObj kvs) k = any ((== k) . fst) kvs
+objHas _ _          = False
+
+normalize :: String -> String -> Int -> Json -> Entry
+normalize fn g idx rawEntry = Entry
+  { function = fn
+  , group    = g
+  , index    = idx
+  , eid      = case objLookup rawEntry "id" of
+                 Just v | not (isNullJson v) -> Just (jsonToString v)
+                 _                           -> Nothing
+  , doc      = case objLookup rawEntry "doc" of Just (JBool True) -> True; _ -> False
+  , client   = case objLookup rawEntry "client" of
+                 Just v | not (isNullJson v) -> Just (jsonToString v)
+                 _                           -> Nothing
+  , input    = resolveInput rawEntry
+  , expect   = resolveExpect rawEntry
+  , eraw     = rawEntry
+  }
+  where
+    isNullJson JNull = True
+    isNullJson _     = False
+    -- id/client are coerced to string (mirrors String(raw.id)); for the corpus
+    -- these are already strings.
+    jsonToString (JStr s) = s
+    jsonToString v        = stringify v
+
+resolveInput :: Json -> Input
+resolveInput rawEntry
+  | objHas rawEntry "ctx"  = Input KCtx  (must "ctx")
+  | objHas rawEntry "args" = Input KArgs (must "args")
+  | otherwise              = Input KIn  (if objHas rawEntry "in" then must "in" else JNull)
+  where
+    must k = maybe JNull id (objLookup rawEntry k)
+
+parseErr :: Json -> ErrorCheck
+parseErr err = case err of
+  JBool True -> ErrorCheck True Nothing False
+  JStr s     -> case regexInner s of
+                  Just inner -> ErrorCheck False (Just inner) True
+                  Nothing    -> ErrorCheck False (Just s) False
+  -- Non-true, non-string err spec: treat as "any error".
+  _          -> ErrorCheck True Nothing False
+
+-- Match "/…/" — leading and trailing slash with at least one inner char.
+regexInner :: String -> Maybe String
+regexInner s
+  | length s >= 3 && head s == '/' && last s == '/' =
+      Just (take (length s - 2) (drop 1 s))
+  | otherwise = Nothing
+
+resolveExpect :: Json -> Expect
+resolveExpect rawEntry
+  | objHas rawEntry "err" =
+      Expect EError Nothing (Just (parseErr (forceLookup "err"))) matchPart
+  | objHas rawEntry "out" =
+      Expect EValue (Just (forceLookup "out")) Nothing matchPart
+  | objHas rawEntry "match" =
+      Expect EMatch Nothing Nothing (Just (forceLookup "match"))
+  | otherwise =
+      Expect EAbsent Nothing Nothing Nothing
+  where
+    matchPart = if objHas rawEntry "match" then objLookup rawEntry "match" else Nothing
+    forceLookup k = maybe JNull id (objLookup rawEntry k)
+
+-- ─── Pure comparison helpers (PROVIDER.md §5) ──────────────────────────────
+
+-- stringify(x) = the string if it is already a string, else compact JSON.
+stringify :: Json -> String
+stringify (JStr s) = s
+stringify v        = compactJson v
+
+compactJson :: Json -> String
+compactJson v = case v of
+  JNull    -> "null"
+  JBool b  -> if b then "true" else "false"
+  JNum d   -> showNum d
+  JStr s   -> showJsonString s
+  JArr xs  -> "[" ++ intercalate "," (map compactJson xs) ++ "]"
+  JObj kvs -> "{" ++ intercalate "," (map kv kvs) ++ "}"
+  where
+    kv (k, x) = showJsonString k ++ ":" ++ compactJson x
+
+-- Compact number rendering close to JSON: integral doubles print without a
+-- trailing ".0" (mirrors JSON.stringify).
+showNum :: Double -> String
+showNum d
+  | isNaN d || isInfinite d = "null"
+  | d == fromIntegral i     = show i
+  | otherwise               = show d
+  where i = round d :: Integer
+
+showJsonString :: String -> String
+showJsonString s = "\"" ++ concatMap esc s ++ "\""
+  where
+    esc c = case c of
+      '"'  -> "\\\""
+      '\\' -> "\\\\"
+      '\n' -> "\\n"
+      '\t' -> "\\t"
+      '\r' -> "\\r"
+      '\b' -> "\\b"
+      '\f' -> "\\f"
+      _ | c < ' ' -> "\\u" ++ pad4 (showHex (fromEnum c) "")
+        | otherwise -> [c]
+    pad4 h = replicate (4 - length h) '0' ++ h
+
+intercalate :: String -> [String] -> String
+intercalate _ []     = ""
+intercalate _ [x]    = x
+intercalate sep (x:xs) = x ++ sep ++ intercalate sep xs
+
+-- normNull: __NULL__ → null, recurse through arrays/objects (mirrors normNull).
+normNull :: Json -> Json
+normNull x = case x of
+  JStr s | s == nullmark -> JNull
+  JArr xs                -> JArr (map normNull xs)
+  JObj kvs               -> JObj [(k, normNull v) | (k, v) <- kvs]
+  _                      -> x
+
+-- normMark: only __NULL__ → null (strict variant).
+normMark :: Json -> Json
+normMark x = case x of
+  JStr s | s == nullmark -> JNull
+  JArr xs                -> JArr (map normMark xs)
+  JObj kvs               -> JObj [(k, normMark v) | (k, v) <- kvs]
+  _                      -> x
+
+-- matchval(check, base): check == base; else if check is a string:
+--   "/re/" ⇒ regex test over stringify(base) (PROTOTYPE: regex simplified),
+--   otherwise stringify(base) contains check, case-insensitively.
+-- (No function case in the Json model — JFunc does not exist here.)
+matchval :: Json -> Json -> Bool
+matchval check base
+  | check == base = True
+  | otherwise = case check of
+      JStr cs ->
+        let basestr = stringify base
+        in case regexInner cs of
+             Just re -> regexLike re basestr
+             Nothing -> map toLower cs `isInfixOf` map toLower basestr
+      _ -> False
+
+-- PROTOTYPE: regex simplified. `base` has no regex engine; we approximate a
+-- "/re/" check by case-sensitive substring containment of the inner pattern.
+-- This is intentionally weaker than a real RegExp and is documented as such.
+regexLike :: String -> String -> Bool
+regexLike re hay = re `isInfixOf` hay
+
+equal :: Json -> Json -> Bool
+equal expected actual = deepEq (normNull expected) (normNull actual)
+
+equalStrict :: Json -> Json -> Bool
+equalStrict expected actual = deepEq (normMark expected) (normMark actual)
+
+-- deepEq mirrors the canonical deepEq: arrays by length+elementwise; objects by
+-- key count + membership; primitives by value. (Eq Json already implements
+-- these semantics, including bool/number distinction via constructors.)
+deepEq :: Json -> Json -> Bool
+deepEq = (==)
+
+errorMatches :: ErrorCheck -> String -> Bool
+errorMatches check message
+  | anyErr check = True
+  | otherwise = case etext check of
+      Nothing   -> False
+      Just text ->
+        if eregex check
+          then regexLike text message               -- PROTOTYPE: regex simplified
+          else map toLower text `isInfixOf` map toLower message
+
+-- ─── structMatch ────────────────────────────────────────────────────────────
+
+data MatchResult = MatchResult
+  { ok        :: Bool
+  , mpath     :: [String]
+  , mexpected :: Maybe Json
+  , mactual   :: Maybe Json
+  } deriving (Show)
+
+okResult :: MatchResult
+okResult = MatchResult True [] Nothing Nothing
+
+-- Partial structural match: every leaf of `check` must match `base` at its path.
+-- Mirrors the canonical structMatch, with `__UNDEF__` requiring absence and
+-- `__EXISTS__` requiring presence. First failure returns its path + values.
+structMatch :: Json -> Json -> MatchResult
+structMatch check base = go (walkLeaves check [])
+  where
+    go [] = okResult
+    go ((val, path) : rest) =
+      let baseval = getpath base path  -- Maybe Json; Nothing == undefined/absent
+      in if leafOk val baseval
+           then go rest
+           else MatchResult False path (Just val) baseval
+    leafOk val baseval =
+      case baseval of
+        Just bv | val == bv -> True
+        _ ->
+          case val of
+            JStr s | s == undefmark -> baseval == Nothing
+            JStr s | s == existsmark ->
+              case baseval of Just bv -> not (isNullJson bv); Nothing -> False
+            _ -> matchval val (maybe JNull id baseval)
+    isNullJson JNull = True
+    isNullJson _     = False
+
+-- Walk to leaves, collecting (leafValue, path). Objects and non-empty arrays
+-- recurse; scalars (and—per the canonical isNode—nulls/bools/numbers/strings)
+-- are leaves. Empty containers are NOT leaves (matching walkLeaves: an empty
+-- object/array yields no leaves), consistent with the canon.
+walkLeaves :: Json -> [String] -> [(Json, [String])]
+walkLeaves node path = case node of
+  JArr xs  -> concat (zipWith (\i v -> walkLeaves v (path ++ [show i])) [0 :: Int ..] xs)
+  JObj kvs -> concatMap (\(k, v) -> walkLeaves v (path ++ [k])) kvs
+  _        -> [(node, path)]
+
+-- getpath over the Json model: Nothing means undefined (absent or off the end).
+getpath :: Json -> [String] -> Maybe Json
+getpath store [] = Just store
+getpath store (key : rest) = case store of
+  JNull   -> Nothing
+  JArr xs -> case readIndex key of
+               Just i | i >= 0 && i < length xs -> getpath (xs !! i) rest
+               _                                -> Nothing
+  JObj kvs -> case lookup key kvs of
+                Just v  -> getpath v rest
+                Nothing -> Nothing
+  _ -> Nothing
+
+readIndex :: String -> Maybe Int
+readIndex s = case reads s of [(i, "")] -> Just i; _ -> Nothing
diff --git a/test/proto/haskell/Smoke.hs b/test/proto/haskell/Smoke.hs
new file mode 100644
index 0000000..f64e151
--- /dev/null
+++ b/test/proto/haskell/Smoke.hs
@@ -0,0 +1,105 @@
+-- Smoke test for the Haskell test provider port. Prints summary stats that
+-- must match the canonical TS output documented in PROVIDER work.
+--
+-- NOTE: GHC is unavailable in this environment; this has NOT been compiled or
+-- executed. The expected output (per the task) is:
+--
+--   functions: minor, getpath, inject, merge, transform, walk, validate, select, sentinels
+--   total entries: 1325
+--   expect kinds: value=1181, absent=84, match=1, error=59
+--   input kinds: in=1325
+--   getpath/basic[0]: id=getpath/basic#deep, doc=true, input.kind=in,
+--                     expect.kind=value, expect.value=42
+
+module Main (main) where
+
+import Data.List (sort)
+
+import Provider
+
+main :: IO ()
+main = do
+  prov <- load Nothing
+
+  let fns = functions prov
+  putStrLn ("functions: " ++ intercalate ", " fns)
+
+  let allEntries = concatMap (\fn -> entries prov fn Nothing) fns
+      total = length allEntries
+      ekTallies = tally (map (expectKindName . ekind . expect) allEntries)
+      ikTallies = tally (map (inputKindName . ikind . input) allEntries)
+
+  putStrLn ("total entries: " ++ show total)
+  putStrLn ("expect kinds: " ++ renderTally ekTallies)
+  putStrLn ("input kinds: " ++ renderTally ikTallies)
+
+  let e = head (entries prov "getpath" (Just "basic"))
+  putStrLn $
+    "getpath/basic[0]: "
+      ++ "id=" ++ maybe "null" id (eid e)
+      ++ ", doc=" ++ boolStr (doc e)
+      ++ ", input.kind=" ++ inputKindName (ikind (input e))
+      ++ ", expect.kind=" ++ expectKindName (ekind (expect e))
+      ++ ", expect.value=" ++ maybe "null" stringify (evalue (expect e))
+
+  -- helper sanity checks
+  putStrLn ("equal(null, null) lenient: " ++ boolStr (equal JNull JNull))
+  putStrLn
+    ( "equalStrict null vs __NULL__-collapse: "
+        ++ boolStr (equalStrict JNull (JStr "__NULL__"))
+        ++ " / "
+        ++ boolStr (equalStrict JNull (JNum 1))
+    )
+  putStrLn
+    ( "errorMatches substring case-insensitive: "
+        ++ boolStr (errorMatches (ErrorCheck False (Just "Foo") False) "a foobar error")
+    )
+  let sm = structMatch (JObj [("a", JObj [("b", JNum 2)])])
+                        (JObj [("a", JObj [("b", JNum 3)])])
+  putStrLn ("structMatch failure: " ++ showMatch sm)
+
+-- ─── helpers ────────────────────────────────────────────────────────────────
+
+expectKindName :: ExpectKind -> String
+expectKindName EValue  = "value"
+expectKindName EError  = "error"
+expectKindName EMatch  = "match"
+expectKindName EAbsent = "absent"
+
+inputKindName :: InputKind -> String
+inputKindName KIn   = "in"
+inputKindName KArgs = "args"
+inputKindName KCtx  = "ctx"
+
+boolStr :: Bool -> String
+boolStr True  = "true"
+boolStr False = "false"
+
+-- Count occurrences, returning (key, count) sorted by key (matches the Python
+-- smoke's `sorted(kinds)` ordering).
+tally :: [String] -> [(String, Int)]
+tally xs = [(k, length (filter (== k) xs)) | k <- sort (uniq xs)]
+
+uniq :: [String] -> [String]
+uniq = go []
+  where
+    go seen [] = reverse seen
+    go seen (x : rest)
+      | x `elem` seen = go seen rest
+      | otherwise     = go (x : seen) rest
+
+renderTally :: [(String, Int)] -> String
+renderTally ts = intercalate ", " [k ++ "=" ++ show v | (k, v) <- ts]
+
+intercalate :: String -> [String] -> String
+intercalate _ []       = ""
+intercalate _ [x]      = x
+intercalate sep (x:xs) = x ++ sep ++ intercalate sep xs
+
+showMatch :: MatchResult -> String
+showMatch m =
+  "{ok=" ++ boolStr (ok m)
+    ++ ", path=[" ++ intercalate "," (mpath m) ++ "]"
+    ++ ", expected=" ++ maybe "-" stringify (mexpected m)
+    ++ ", actual=" ++ maybe "-" stringify (mactual m)
+    ++ "}"
diff --git a/test/proto/java/Json.java b/test/proto/java/Json.java
new file mode 100644
index 0000000..a407e0d
--- /dev/null
+++ b/test/proto/java/Json.java
@@ -0,0 +1,367 @@
+// Minimal dependency-free JSON parser and serializer for the Java test provider.
+//
+// Parses into java.lang.Object trees:
+//   - objects -> java.util.LinkedHashMap<String,Object>  (PRESERVES key order)
+//   - arrays  -> java.util.ArrayList<Object>
+//   - strings -> String
+//   - numbers -> Double
+//   - true/false -> Boolean
+//   - null -> null
+//
+// JDK standard library only. No Gson, no Jackson, no third-party libs.
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+public final class Json {
+
+  private Json() {}
+
+  // ─── parsing ───────────────────────────────────────────────────────────────
+
+  public static Object parse(String text) {
+    Parser p = new Parser(text);
+    p.skipWs();
+    Object v = p.parseValue();
+    p.skipWs();
+    if (!p.atEnd()) {
+      throw new JsonException("Trailing content at position " + p.pos);
+    }
+    return v;
+  }
+
+  public static class JsonException extends RuntimeException {
+    public JsonException(String msg) {
+      super(msg);
+    }
+  }
+
+  private static final class Parser {
+    final String s;
+    int pos;
+
+    Parser(String s) {
+      this.s = s;
+    }
+
+    boolean atEnd() {
+      return pos >= s.length();
+    }
+
+    void skipWs() {
+      while (pos < s.length()) {
+        char c = s.charAt(pos);
+        if (c == ' ' || c == '\t' || c == '\n' || c == '\r') {
+          pos++;
+        } else {
+          break;
+        }
+      }
+    }
+
+    char peek() {
+      if (pos >= s.length()) {
+        throw new JsonException("Unexpected end of input");
+      }
+      return s.charAt(pos);
+    }
+
+    Object parseValue() {
+      skipWs();
+      char c = peek();
+      switch (c) {
+        case '{':
+          return parseObject();
+        case '[':
+          return parseArray();
+        case '"':
+          return parseString();
+        case 't':
+        case 'f':
+          return parseBool();
+        case 'n':
+          return parseNull();
+        default:
+          if (c == '-' || (c >= '0' && c <= '9')) {
+            return parseNumber();
+          }
+          throw new JsonException("Unexpected char '" + c + "' at position " + pos);
+      }
+    }
+
+    Map<String, Object> parseObject() {
+      Map<String, Object> m = new LinkedHashMap<>();
+      pos++; // consume '{'
+      skipWs();
+      if (peek() == '}') {
+        pos++;
+        return m;
+      }
+      while (true) {
+        skipWs();
+        if (peek() != '"') {
+          throw new JsonException("Expected string key at position " + pos);
+        }
+        String key = parseString();
+        skipWs();
+        if (peek() != ':') {
+          throw new JsonException("Expected ':' at position " + pos);
+        }
+        pos++; // consume ':'
+        Object val = parseValue();
+        m.put(key, val);
+        skipWs();
+        char c = peek();
+        if (c == ',') {
+          pos++;
+          continue;
+        }
+        if (c == '}') {
+          pos++;
+          break;
+        }
+        throw new JsonException("Expected ',' or '}' at position " + pos);
+      }
+      return m;
+    }
+
+    List<Object> parseArray() {
+      List<Object> list = new ArrayList<>();
+      pos++; // consume '['
+      skipWs();
+      if (peek() == ']') {
+        pos++;
+        return list;
+      }
+      while (true) {
+        Object val = parseValue();
+        list.add(val);
+        skipWs();
+        char c = peek();
+        if (c == ',') {
+          pos++;
+          continue;
+        }
+        if (c == ']') {
+          pos++;
+          break;
+        }
+        throw new JsonException("Expected ',' or ']' at position " + pos);
+      }
+      return list;
+    }
+
+    String parseString() {
+      pos++; // consume opening '"'
+      StringBuilder sb = new StringBuilder();
+      while (true) {
+        if (pos >= s.length()) {
+          throw new JsonException("Unterminated string");
+        }
+        char c = s.charAt(pos++);
+        if (c == '"') {
+          break;
+        }
+        if (c == '\\') {
+          if (pos >= s.length()) {
+            throw new JsonException("Unterminated escape");
+          }
+          char e = s.charAt(pos++);
+          switch (e) {
+            case '"':
+              sb.append('"');
+              break;
+            case '\\':
+              sb.append('\\');
+              break;
+            case '/':
+              sb.append('/');
+              break;
+            case 'b':
+              sb.append('\b');
+              break;
+            case 'f':
+              sb.append('\f');
+              break;
+            case 'n':
+              sb.append('\n');
+              break;
+            case 'r':
+              sb.append('\r');
+              break;
+            case 't':
+              sb.append('\t');
+              break;
+            case 'u':
+              if (pos + 4 > s.length()) {
+                throw new JsonException("Invalid \\u escape");
+              }
+              String hex = s.substring(pos, pos + 4);
+              pos += 4;
+              try {
+                sb.append((char) Integer.parseInt(hex, 16));
+              } catch (NumberFormatException nfe) {
+                throw new JsonException("Invalid \\u escape: " + hex);
+              }
+              break;
+            default:
+              throw new JsonException("Invalid escape '\\" + e + "'");
+          }
+        } else {
+          sb.append(c);
+        }
+      }
+      return sb.toString();
+    }
+
+    Boolean parseBool() {
+      if (s.startsWith("true", pos)) {
+        pos += 4;
+        return Boolean.TRUE;
+      }
+      if (s.startsWith("false", pos)) {
+        pos += 5;
+        return Boolean.FALSE;
+      }
+      throw new JsonException("Invalid literal at position " + pos);
+    }
+
+    Object parseNull() {
+      if (s.startsWith("null", pos)) {
+        pos += 4;
+        return null;
+      }
+      throw new JsonException("Invalid literal at position " + pos);
+    }
+
+    Double parseNumber() {
+      int start = pos;
+      if (peek() == '-') {
+        pos++;
+      }
+      while (pos < s.length() && Character.isDigit(s.charAt(pos))) {
+        pos++;
+      }
+      if (pos < s.length() && s.charAt(pos) == '.') {
+        pos++;
+        while (pos < s.length() && Character.isDigit(s.charAt(pos))) {
+          pos++;
+        }
+      }
+      if (pos < s.length() && (s.charAt(pos) == 'e' || s.charAt(pos) == 'E')) {
+        pos++;
+        if (pos < s.length() && (s.charAt(pos) == '+' || s.charAt(pos) == '-')) {
+          pos++;
+        }
+        while (pos < s.length() && Character.isDigit(s.charAt(pos))) {
+          pos++;
+        }
+      }
+      String num = s.substring(start, pos);
+      try {
+        return Double.parseDouble(num);
+      } catch (NumberFormatException nfe) {
+        throw new JsonException("Invalid number '" + num + "'");
+      }
+    }
+  }
+
+  // ─── serialization ───────────────────────────────────────────────────────────
+
+  // Compact JSON serialization. Whole-number Doubles render without a trailing
+  // ".0" (so 42.0 -> "42"), matching the canonical stringify expectations.
+  public static String stringify(Object v) {
+    StringBuilder sb = new StringBuilder();
+    write(v, sb);
+    return sb.toString();
+  }
+
+  @SuppressWarnings("unchecked")
+  private static void write(Object v, StringBuilder sb) {
+    if (v == null) {
+      sb.append("null");
+    } else if (v instanceof String) {
+      writeString((String) v, sb);
+    } else if (v instanceof Double) {
+      writeNumber((Double) v, sb);
+    } else if (v instanceof Number) {
+      // Other numeric types (Long, Integer, etc.) — render plainly.
+      writeNumber(((Number) v).doubleValue(), sb);
+    } else if (v instanceof Boolean) {
+      sb.append(((Boolean) v) ? "true" : "false");
+    } else if (v instanceof Map) {
+      sb.append('{');
+      boolean first = true;
+      for (Map.Entry<?, ?> e : ((Map<?, ?>) v).entrySet()) {
+        if (!first) {
+          sb.append(',');
+        }
+        first = false;
+        writeString(String.valueOf(e.getKey()), sb);
+        sb.append(':');
+        write(e.getValue(), sb);
+      }
+      sb.append('}');
+    } else if (v instanceof List) {
+      sb.append('[');
+      boolean first = true;
+      for (Object x : (List<Object>) v) {
+        if (!first) {
+          sb.append(',');
+        }
+        first = false;
+        write(x, sb);
+      }
+      sb.append(']');
+    } else {
+      writeString(String.valueOf(v), sb);
+    }
+  }
+
+  private static void writeNumber(double d, StringBuilder sb) {
+    if (Double.isFinite(d) && Math.floor(d) == d && Math.abs(d) < 1e15) {
+      sb.append(Long.toString((long) d));
+    } else {
+      sb.append(Double.toString(d));
+    }
+  }
+
+  private static void writeString(String s, StringBuilder sb) {
+    sb.append('"');
+    for (int i = 0; i < s.length(); i++) {
+      char c = s.charAt(i);
+      switch (c) {
+        case '"':
+          sb.append("\\\"");
+          break;
+        case '\\':
+          sb.append("\\\\");
+          break;
+        case '\b':
+          sb.append("\\b");
+          break;
+        case '\f':
+          sb.append("\\f");
+          break;
+        case '\n':
+          sb.append("\\n");
+          break;
+        case '\r':
+          sb.append("\\r");
+          break;
+        case '\t':
+          sb.append("\\t");
+          break;
+        default:
+          if (c < 0x20) {
+            sb.append(String.format("\\u%04x", (int) c));
+          } else {
+            sb.append(c);
+          }
+      }
+    }
+    sb.append('"');
+  }
+}
diff --git a/test/proto/java/Provider.java b/test/proto/java/Provider.java
new file mode 100644
index 0000000..bf3e73f
--- /dev/null
+++ b/test/proto/java/Provider.java
@@ -0,0 +1,516 @@
+// Test Provider (prototype) — Java port of the canonical ts/provider.ts.
+//
+// Reads the shared corpus (build/test/test.json) and hands test code clean,
+// normalized cases. It is NOT a test runner: it never calls the subject and
+// never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+//
+// Zero runtime dependencies (JDK standard library only) — uses the bundled
+// minimal Json parser instead of Gson/Jackson.
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+@SuppressWarnings({"unchecked", "rawtypes"})
+public class Provider {
+
+  public static final String NULLMARK = "__NULL__";
+  public static final String UNDEFMARK = "__UNDEF__";
+  public static final String EXISTSMARK = "__EXISTS__";
+
+  // Sentinel distinguishing "key absent" from "value is null" in getpath.
+  private static final Object MISSING = new Object();
+
+  private final Object spec;
+
+  public Provider(Object spec) {
+    this.spec = spec;
+  }
+
+  // ─── loading ─────────────────────────────────────────────────────────────
+
+  // Default corpus path resolves to build/test/test.json relative to the repo
+  // root (this file lives at test/proto/java). A non-null path is used as-is,
+  // so callers (e.g. the smoke harness running from the repo root) may pass an
+  // absolute or repo-relative path directly.
+  public static Provider load(String path) {
+    String file = path != null ? path : defaultTestFile();
+    try {
+      String json = new String(Files.readAllBytes(Paths.get(file)), StandardCharsets.UTF_8);
+      return new Provider(Json.parse(json));
+    } catch (IOException e) {
+      throw new RuntimeException("Failed to read corpus: " + file, e);
+    }
+  }
+
+  private static String defaultTestFile() {
+    // This source is at test/proto/java; the corpus is four levels up.
+    Path here = Paths.get(System.getProperty("user.dir"));
+    return here.resolve(Paths.get("build", "test", "test.json")).toString();
+  }
+
+  public Object raw() {
+    return spec;
+  }
+
+  private Map<String, Object> root() {
+    if (spec instanceof Map) {
+      Object struct = ((Map<String, Object>) spec).get("struct");
+      if (struct instanceof Map) {
+        return (Map<String, Object>) struct;
+      }
+      return (Map<String, Object>) spec;
+    }
+    return new LinkedHashMap<>();
+  }
+
+  private Map<String, Object> fnNode(String fn) {
+    Object node = null;
+    if (spec instanceof Map) {
+      Object struct = ((Map<String, Object>) spec).get("struct");
+      if (struct instanceof Map && ((Map<String, Object>) struct).containsKey(fn)) {
+        node = ((Map<String, Object>) struct).get(fn);
+      } else if (((Map<String, Object>) spec).containsKey(fn)) {
+        node = ((Map<String, Object>) spec).get(fn);
+      }
+    }
+    if (node == null) {
+      throw new IllegalArgumentException("Unknown function: " + fn);
+    }
+    return (Map<String, Object>) node;
+  }
+
+  public List<String> functions() {
+    Map<String, Object> root = root();
+    List<String> out = new ArrayList<>();
+    for (Map.Entry<String, Object> e : root.entrySet()) {
+      if (isGroupBag(e.getValue()) || hasGroups(e.getValue())) {
+        out.add(e.getKey());
+      }
+    }
+    return out;
+  }
+
+  public List<String> groups(String fn) {
+    Map<String, Object> node = fnNode(fn);
+    List<String> out = new ArrayList<>();
+    for (Map.Entry<String, Object> e : node.entrySet()) {
+      if (!"name".equals(e.getKey()) && isGroupBag(e.getValue())) {
+        out.add(e.getKey());
+      }
+    }
+    return out;
+  }
+
+  // group == null means "all groups for the function".
+  public List<Entry> entries(String fn, String group) {
+    Map<String, Object> node = fnNode(fn);
+    List<String> groupList = group != null ? List.of(group) : groups(fn);
+    List<Entry> out = new ArrayList<>();
+    for (String g : groupList) {
+      Object bag = node.get(g);
+      if (!isGroupBag(bag)) {
+        continue;
+      }
+      List<Object> set = (List<Object>) ((Map<String, Object>) bag).get("set");
+      for (int i = 0; i < set.size(); i++) {
+        out.add(normalize(fn, g, i, (Map<String, Object>) set.get(i)));
+      }
+    }
+    return out;
+  }
+
+  // A group bag is a map with a `set` list.
+  private static boolean isGroupBag(Object v) {
+    return v instanceof Map && ((Map<String, Object>) v).get("set") instanceof List;
+  }
+
+  // A function node has at least one child group bag.
+  private static boolean hasGroups(Object v) {
+    if (!(v instanceof Map)) {
+      return false;
+    }
+    for (Map.Entry<String, Object> e : ((Map<String, Object>) v).entrySet()) {
+      if (!"name".equals(e.getKey()) && isGroupBag(e.getValue())) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  // ─── normalized records ──────────────────────────────────────────────────
+
+  public static final class Input {
+    public enum Kind {
+      IN,
+      ARGS,
+      CTX
+    }
+
+    public Kind kind;
+    public Object in;
+    public List<Object> args;
+    public Map<String, Object> ctx;
+  }
+
+  public static final class ErrorCheck {
+    public boolean any;
+    public String text;
+    public boolean regex;
+  }
+
+  public static final class Expect {
+    public enum Kind {
+      VALUE,
+      ERROR,
+      MATCH,
+      ABSENT
+    }
+
+    public Kind kind;
+    public boolean hasValue;
+    public Object value;
+    public ErrorCheck error;
+    public Object match;
+  }
+
+  public static final class Entry {
+    public String function;
+    public String group;
+    public int index;
+    public String id;
+    public boolean doc;
+    public String client;
+    public Input input;
+    public Expect expect;
+    public Object raw;
+  }
+
+  public static final class MatchResult {
+    public boolean ok;
+    public List<String> path;
+    public Object expected;
+    public Object actual;
+  }
+
+  private static boolean has(Map<String, Object> raw, String key) {
+    return raw.containsKey(key);
+  }
+
+  private static Entry normalize(String fn, String group, int index, Map<String, Object> raw) {
+    Entry e = new Entry();
+    e.function = fn;
+    e.group = group;
+    e.index = index;
+    Object id = raw.get("id");
+    e.id = id != null ? String.valueOf(id) : null;
+    e.doc = Boolean.TRUE.equals(raw.get("doc"));
+    Object client = raw.get("client");
+    e.client = client != null ? String.valueOf(client) : null;
+    e.input = resolveInput(raw);
+    e.expect = resolveExpect(raw);
+    e.raw = raw;
+    return e;
+  }
+
+  private static Input resolveInput(Map<String, Object> raw) {
+    Input in = new Input();
+    if (has(raw, "ctx")) {
+      in.kind = Input.Kind.CTX;
+      in.ctx = (Map<String, Object>) raw.get("ctx");
+      return in;
+    }
+    if (has(raw, "args")) {
+      in.kind = Input.Kind.ARGS;
+      in.args = (List<Object>) raw.get("args");
+      return in;
+    }
+    in.kind = Input.Kind.IN;
+    in.in = has(raw, "in") ? raw.get("in") : null;
+    return in;
+  }
+
+  private static ErrorCheck parseErr(Object err) {
+    ErrorCheck c = new ErrorCheck();
+    if (Boolean.TRUE.equals(err)) {
+      c.any = true;
+      return c;
+    }
+    if (err instanceof String) {
+      String s = (String) err;
+      Matcher m = Pattern.compile("^/(.+)/$").matcher(s);
+      if (m.matches()) {
+        c.regex = true;
+        c.text = m.group(1);
+        return c;
+      }
+      c.text = s;
+      return c;
+    }
+    // Non-true, non-string err spec: treat as "any error".
+    c.any = true;
+    return c;
+  }
+
+  private static Expect resolveExpect(Map<String, Object> raw) {
+    Object matchPart = has(raw, "match") ? raw.get("match") : null;
+    Expect ex = new Expect();
+    if (has(raw, "err")) {
+      ex.kind = Expect.Kind.ERROR;
+      ex.error = parseErr(raw.get("err"));
+      ex.match = matchPart;
+      return ex;
+    }
+    // KEY PRESENCE, not null-check: "out" present even if null => VALUE.
+    if (has(raw, "out")) {
+      ex.kind = Expect.Kind.VALUE;
+      ex.hasValue = true;
+      ex.value = raw.get("out");
+      ex.match = matchPart;
+      return ex;
+    }
+    if (has(raw, "match")) {
+      ex.kind = Expect.Kind.MATCH;
+      ex.match = raw.get("match");
+      return ex;
+    }
+    ex.kind = Expect.Kind.ABSENT;
+    return ex;
+  }
+
+  // ─── pure comparison helpers ─────────────────────────────────────────────
+
+  // stringify(x) = x if it is already a String, else compact JSON.
+  public static String stringify(Object x) {
+    return x instanceof String ? (String) x : Json.stringify(x);
+  }
+
+  private static Object normNull(Object x) {
+    if (NULLMARK.equals(x) || x == null) {
+      return null;
+    }
+    if (x instanceof List) {
+      List<Object> out = new ArrayList<>();
+      for (Object v : (List<Object>) x) {
+        out.add(normNull(v));
+      }
+      return out;
+    }
+    if (x instanceof Map) {
+      Map<String, Object> out = new LinkedHashMap<>();
+      for (Map.Entry<String, Object> e : ((Map<String, Object>) x).entrySet()) {
+        out.put(e.getKey(), normNull(e.getValue()));
+      }
+      return out;
+    }
+    return x;
+  }
+
+  private static Object normMark(Object x) {
+    if (NULLMARK.equals(x)) {
+      return null;
+    }
+    if (x instanceof List) {
+      List<Object> out = new ArrayList<>();
+      for (Object v : (List<Object>) x) {
+        out.add(normMark(v));
+      }
+      return out;
+    }
+    if (x instanceof Map) {
+      Map<String, Object> out = new LinkedHashMap<>();
+      for (Map.Entry<String, Object> e : ((Map<String, Object>) x).entrySet()) {
+        out.put(e.getKey(), normMark(e.getValue()));
+      }
+      return out;
+    }
+    return x;
+  }
+
+  public static boolean matchval(Object check, Object base) {
+    if (scalarEq(check, base)) {
+      return true;
+    }
+    if (check instanceof String) {
+      String chk = (String) check;
+      String basestr = stringify(base);
+      Matcher rem = Pattern.compile("^/(.+)/$").matcher(chk);
+      if (rem.matches()) {
+        return Pattern.compile(rem.group(1)).matcher(basestr).find();
+      }
+      return basestr.toLowerCase().contains(chk.toLowerCase());
+    }
+    // A "function" check (not representable from JSON) would return true; no
+    // such value arises from the parsed corpus.
+    return false;
+  }
+
+  public static boolean equal(Object expected, Object actual) {
+    return deepEq(normNull(expected), normNull(actual));
+  }
+
+  // Strict variant for the runner's { null: false } functions, where an absent
+  // value is distinct from JSON null. Only __NULL__ is normalized.
+  public static boolean equalStrict(Object expected, Object actual) {
+    return deepEq(normMark(expected), normMark(actual));
+  }
+
+  // Scalar identity mirroring JS ===: distinguishes Boolean from Number, and
+  // compares numbers/strings/booleans by value.
+  private static boolean scalarEq(Object a, Object b) {
+    if (a == b) {
+      return true;
+    }
+    if (a == null || b == null) {
+      return false;
+    }
+    if ((a instanceof Boolean) != (b instanceof Boolean)) {
+      return false;
+    }
+    if (a instanceof Number && b instanceof Number) {
+      return ((Number) a).doubleValue() == ((Number) b).doubleValue();
+    }
+    return a.equals(b);
+  }
+
+  private static boolean deepEq(Object a, Object b) {
+    if (a == b) {
+      return true;
+    }
+    if (a instanceof List && b instanceof List) {
+      List<Object> la = (List<Object>) a;
+      List<Object> lb = (List<Object>) b;
+      if (la.size() != lb.size()) {
+        return false;
+      }
+      for (int i = 0; i < la.size(); i++) {
+        if (!deepEq(la.get(i), lb.get(i))) {
+          return false;
+        }
+      }
+      return true;
+    }
+    if (a instanceof List || b instanceof List) {
+      return false;
+    }
+    if (a instanceof Map && b instanceof Map) {
+      Map<String, Object> ma = (Map<String, Object>) a;
+      Map<String, Object> mb = (Map<String, Object>) b;
+      if (ma.size() != mb.size()) {
+        return false;
+      }
+      for (Map.Entry<String, Object> e : ma.entrySet()) {
+        if (!mb.containsKey(e.getKey()) || !deepEq(e.getValue(), mb.get(e.getKey()))) {
+          return false;
+        }
+      }
+      return true;
+    }
+    if (a instanceof Map || b instanceof Map) {
+      return false;
+    }
+    return scalarEq(a, b);
+  }
+
+  public static boolean errorMatches(ErrorCheck check, String message) {
+    if (check.any) {
+      return true;
+    }
+    if (check.text == null) {
+      return false;
+    }
+    if (check.regex) {
+      return Pattern.compile(check.text).matcher(message).find();
+    }
+    return message.toLowerCase().contains(check.text.toLowerCase());
+  }
+
+  // Partial structural match: every leaf of `check` must match `base` at its path.
+  public static MatchResult structMatch(Object check, Object base) {
+    MatchResult result = new MatchResult();
+    result.ok = true;
+    walkLeaves(
+        check,
+        new ArrayList<>(),
+        (val, path) -> {
+          if (!result.ok) {
+            return;
+          }
+          Object baseval = getpath(base, path);
+          if (baseval != MISSING && scalarEq(val, baseval)) {
+            return;
+          }
+          if (UNDEFMARK.equals(val) && baseval == MISSING) {
+            return;
+          }
+          if (EXISTSMARK.equals(val) && baseval != MISSING && baseval != null) {
+            return;
+          }
+          Object compareBase = baseval == MISSING ? null : baseval;
+          if (!matchval(val, compareBase)) {
+            result.ok = false;
+            result.path = path;
+            result.expected = val;
+            result.actual = compareBase;
+          }
+        });
+    return result;
+  }
+
+  private interface LeafFn {
+    void visit(Object val, List<String> path);
+  }
+
+  private static void walkLeaves(Object node, List<String> path, LeafFn fn) {
+    if (node instanceof List) {
+      List<Object> l = (List<Object>) node;
+      for (int i = 0; i < l.size(); i++) {
+        List<String> next = new ArrayList<>(path);
+        next.add(String.valueOf(i));
+        walkLeaves(l.get(i), next, fn);
+      }
+    } else if (node instanceof Map) {
+      for (Map.Entry<String, Object> e : ((Map<String, Object>) node).entrySet()) {
+        List<String> next = new ArrayList<>(path);
+        next.add(e.getKey());
+        walkLeaves(e.getValue(), next, fn);
+      }
+    } else {
+      fn.visit(node, path);
+    }
+  }
+
+  // Returns MISSING for an absent path (distinct from a present null).
+  private static Object getpath(Object store, List<String> path) {
+    Object cur = store;
+    for (String key : path) {
+      if (cur == null || cur == MISSING) {
+        return MISSING;
+      }
+      if (cur instanceof List) {
+        List<Object> l = (List<Object>) cur;
+        int idx;
+        try {
+          idx = Integer.parseInt(key);
+        } catch (NumberFormatException nfe) {
+          return MISSING;
+        }
+        cur = (idx >= 0 && idx < l.size()) ? l.get(idx) : MISSING;
+      } else if (cur instanceof Map) {
+        Map<String, Object> m = (Map<String, Object>) cur;
+        cur = m.containsKey(key) ? m.get(key) : MISSING;
+      } else {
+        return MISSING;
+      }
+    }
+    return cur;
+  }
+}
diff --git a/test/proto/java/Smoke.java b/test/proto/java/Smoke.java
new file mode 100644
index 0000000..32ebbf1
--- /dev/null
+++ b/test/proto/java/Smoke.java
@@ -0,0 +1,63 @@
+// Smoke test for the Java test provider port. Prints summary stats that must
+// match the canonical TS output documented in PROVIDER.md.
+//
+// Run from the repo root:
+//   cd test/proto/java && javac *.java && (cd /home/user/struct && java -cp test/proto/java Smoke)
+
+import java.util.List;
+import java.util.Map;
+import java.util.TreeMap;
+
+public class Smoke {
+
+  public static void main(String[] args) {
+    String path = args.length > 0 ? args[0] : "build/test/test.json";
+    Provider prov = Provider.load(path);
+
+    List<String> fns = prov.functions();
+    System.out.println("functions: " + String.join(", ", fns));
+
+    int total = 0;
+    Map<String, Integer> expectKinds = new TreeMap<>();
+    Map<String, Integer> inputKinds = new TreeMap<>();
+    for (String fn : fns) {
+      for (Provider.Entry e : prov.entries(fn, null)) {
+        total++;
+        String ek = e.expect.kind.name().toLowerCase();
+        String ik = e.input.kind.name().toLowerCase();
+        expectKinds.merge(ek, 1, Integer::sum);
+        inputKinds.merge(ik, 1, Integer::sum);
+      }
+    }
+
+    System.out.println("total entries: " + total);
+    System.out.println("expect kinds: " + joinCounts(expectKinds));
+    System.out.println("input kinds: " + joinCounts(inputKinds));
+
+    Provider.Entry e = prov.entries("getpath", "basic").get(0);
+    System.out.println(
+        "getpath/basic[0]: id="
+            + e.id
+            + ", doc="
+            + e.doc
+            + ", input.kind="
+            + e.input.kind.name().toLowerCase()
+            + ", expect.kind="
+            + e.expect.kind.name().toLowerCase()
+            + ", expect.value="
+            + Provider.stringify(e.expect.value));
+  }
+
+  private static String joinCounts(Map<String, Integer> counts) {
+    StringBuilder sb = new StringBuilder();
+    boolean first = true;
+    for (Map.Entry<String, Integer> c : counts.entrySet()) {
+      if (!first) {
+        sb.append(", ");
+      }
+      first = false;
+      sb.append(c.getKey()).append('=').append(c.getValue());
+    }
+    return sb.toString();
+  }
+}
diff --git a/test/proto/javascript/provider.js b/test/proto/javascript/provider.js
new file mode 100644
index 0000000..aba1559
--- /dev/null
+++ b/test/proto/javascript/provider.js
@@ -0,0 +1,292 @@
+// Test Provider (prototype) — JavaScript port of the canonical ts/provider.ts.
+//
+// Reads the shared corpus (build/test/test.json) and hands test code clean,
+// normalized cases. It is NOT a test runner: it never calls the subject and
+// never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+//
+// Zero runtime dependencies (Node built-ins only), matching repo policy.
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const NULLMARK = '__NULL__'
+const UNDEFMARK = '__UNDEF__'
+const EXISTSMARK = '__EXISTS__'
+
+// Default corpus path: build/test/test.json relative to this source file.
+function defaultTestFile() {
+  const here = dirname(fileURLToPath(import.meta.url)) // test/proto/javascript
+  return join(here, '..', '..', '..', 'build', 'test', 'test.json')
+}
+
+export class TestProvider {
+  constructor(spec) {
+    this.spec = spec
+  }
+
+  static load(testfile) {
+    const file = testfile != null ? testfile : defaultTestFile()
+    return new TestProvider(JSON.parse(readFileSync(file, 'utf8')))
+  }
+
+  raw() {
+    return this.spec
+  }
+
+  fnNode(fn) {
+    const node =
+      (this.spec && this.spec.struct && this.spec.struct[fn]) ??
+      (this.spec && this.spec[fn])
+    if (null == node) {
+      throw new Error(`Unknown function: ${fn}`)
+    }
+    return node
+  }
+
+  functions() {
+    const root = (this.spec && this.spec.struct) ?? this.spec
+    return Object.keys(root).filter((k) => isGroupBag(root[k]) || hasGroups(root[k]))
+  }
+
+  groups(fn) {
+    const node = this.fnNode(fn)
+    return Object.keys(node).filter((k) => k !== 'name' && isGroupBag(node[k]))
+  }
+
+  entries(fn, group) {
+    const node = this.fnNode(fn)
+    const groups = group != null ? [group] : this.groups(fn)
+    const out = []
+    for (const g of groups) {
+      const bag = node[g]
+      if (!isGroupBag(bag)) {
+        continue
+      }
+      const set = bag.set
+      for (let i = 0; i < set.length; i++) {
+        out.push(normalize(fn, g, i, set[i]))
+      }
+    }
+    return out
+  }
+}
+
+// A group bag is a map with a `set` array.
+function isGroupBag(v) {
+  return null != v && 'object' === typeof v && !Array.isArray(v) && Array.isArray(v.set)
+}
+
+// A function node has at least one child group bag.
+function hasGroups(v) {
+  return (
+    null != v &&
+    'object' === typeof v &&
+    !Array.isArray(v) &&
+    Object.keys(v).some((k) => k !== 'name' && isGroupBag(v[k]))
+  )
+}
+
+function normalize(fn, group, index, raw) {
+  return {
+    function: fn,
+    group,
+    index,
+    id: null != raw.id ? String(raw.id) : null,
+    doc: true === raw.doc,
+    client: null != raw.client ? String(raw.client) : null,
+    input: resolveInput(raw),
+    expect: resolveExpect(raw),
+    raw,
+  }
+}
+
+function has(raw, key) {
+  return Object.prototype.hasOwnProperty.call(raw, key)
+}
+
+function resolveInput(raw) {
+  if (has(raw, 'ctx')) {
+    return { kind: 'ctx', ctx: raw.ctx }
+  }
+  if (has(raw, 'args')) {
+    return { kind: 'args', args: raw.args }
+  }
+  return { kind: 'in', in: has(raw, 'in') ? raw.in : null }
+}
+
+function parseErr(err) {
+  if (true === err) {
+    return { any: true, text: null, regex: false }
+  }
+  if ('string' === typeof err) {
+    const m = err.match(/^\/(.+)\/$/)
+    if (m) {
+      return { any: false, text: m[1], regex: true }
+    }
+    return { any: false, text: err, regex: false }
+  }
+  // Non-true, non-string err spec: treat as "any error".
+  return { any: true, text: null, regex: false }
+}
+
+function resolveExpect(raw) {
+  const matchPart = has(raw, 'match') ? raw.match : undefined
+  if (has(raw, 'err')) {
+    return { kind: 'error', error: parseErr(raw.err), match: matchPart }
+  }
+  if (has(raw, 'out')) {
+    return { kind: 'value', value: raw.out, match: matchPart }
+  }
+  if (has(raw, 'match')) {
+    return { kind: 'match', match: raw.match }
+  }
+  return { kind: 'absent' }
+}
+
+// ─── pure comparison helpers ───────────────────────────────────────────────
+
+function stringify(x) {
+  return 'string' === typeof x ? x : JSON.stringify(x)
+}
+
+function normNull(x) {
+  if (NULLMARK === x || undefined === x) {
+    return null
+  }
+  if (Array.isArray(x)) {
+    return x.map(normNull)
+  }
+  if (null != x && 'object' === typeof x) {
+    const o = {}
+    for (const k of Object.keys(x)) {
+      o[k] = normNull(x[k])
+    }
+    return o
+  }
+  return x
+}
+
+export function matchval(check, base) {
+  if (check === base) {
+    return true
+  }
+  if ('string' === typeof check) {
+    const basestr = stringify(base)
+    const rem = check.match(/^\/(.+)\/$/)
+    if (rem) {
+      return new RegExp(rem[1]).test(basestr)
+    }
+    return basestr.toLowerCase().includes(check.toLowerCase())
+  }
+  if ('function' === typeof check) {
+    return true
+  }
+  return false
+}
+
+export function equal(expected, actual) {
+  return deepEq(normNull(expected), normNull(actual))
+}
+
+// Strict variant for the runner's `{ null: false }` functions, where an absent
+// value (undefined) is distinct from JSON null. Only __NULL__ is normalized.
+export function equalStrict(expected, actual) {
+  return deepEq(normMark(expected), normMark(actual))
+}
+
+function normMark(x) {
+  if (NULLMARK === x) {
+    return null
+  }
+  if (Array.isArray(x)) {
+    return x.map(normMark)
+  }
+  if (null != x && 'object' === typeof x) {
+    const o = {}
+    for (const k of Object.keys(x)) {
+      o[k] = normMark(x[k])
+    }
+    return o
+  }
+  return x
+}
+
+function deepEq(a, b) {
+  if (a === b) {
+    return true
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => deepEq(v, b[i]))
+  }
+  if (null != a && null != b && 'object' === typeof a && 'object' === typeof b) {
+    const ak = Object.keys(a)
+    const bk = Object.keys(b)
+    return ak.length === bk.length && ak.every((k) => has(b, k) && deepEq(a[k], b[k]))
+  }
+  return false
+}
+
+export function errorMatches(check, message) {
+  if (check.any) {
+    return true
+  }
+  if (null == check.text) {
+    return false
+  }
+  if (check.regex) {
+    return new RegExp(check.text).test(message)
+  }
+  return message.toLowerCase().includes(check.text.toLowerCase())
+}
+
+// Partial structural match: every leaf of `check` must match `base` at its path.
+export function structMatch(check, base) {
+  let result = { ok: true }
+  walkLeaves(check, [], (val, path) => {
+    if (!result.ok) {
+      return
+    }
+    const baseval = getpath(base, path)
+    if (baseval === val) {
+      return
+    }
+    if (UNDEFMARK === val && undefined === baseval) {
+      return
+    }
+    if (EXISTSMARK === val && null != baseval) {
+      return
+    }
+    if (!matchval(val, baseval)) {
+      result = { ok: false, path, expected: val, actual: baseval }
+    }
+  })
+  return result
+}
+
+function isNode(v) {
+  return null != v && 'object' === typeof v
+}
+
+function walkLeaves(node, path, fn) {
+  if (Array.isArray(node)) {
+    node.forEach((v, i) => walkLeaves(v, [...path, String(i)], fn))
+  } else if (isNode(node)) {
+    for (const k of Object.keys(node)) {
+      walkLeaves(node[k], [...path, k], fn)
+    }
+  } else {
+    fn(node, path)
+  }
+}
+
+function getpath(store, path) {
+  let cur = store
+  for (const key of path) {
+    if (null == cur) {
+      return undefined
+    }
+    cur = Array.isArray(cur) ? cur[Number(key)] : cur[key]
+  }
+  return cur
+}
diff --git a/test/proto/javascript/smoke.js b/test/proto/javascript/smoke.js
new file mode 100644
index 0000000..84bfa15
--- /dev/null
+++ b/test/proto/javascript/smoke.js
@@ -0,0 +1,51 @@
+// Smoke test for the JavaScript test-provider port.
+// Loads the corpus and prints summary stats plus one normalized entry.
+
+import { TestProvider } from './provider.js'
+
+const provider = TestProvider.load()
+
+const functions = provider.functions()
+console.log('functions: ' + functions.join(', '))
+
+const expectCounts = {}
+const inputCounts = {}
+let total = 0
+
+for (const fn of functions) {
+  for (const entry of provider.entries(fn)) {
+    total++
+    expectCounts[entry.expect.kind] = (expectCounts[entry.expect.kind] || 0) + 1
+    inputCounts[entry.input.kind] = (inputCounts[entry.input.kind] || 0) + 1
+  }
+}
+
+console.log('total entries: ' + total)
+
+console.log(
+  'expect kinds: ' +
+    Object.keys(expectCounts)
+      .map((k) => `${k}=${expectCounts[k]}`)
+      .join(', '),
+)
+
+console.log(
+  'input kinds: ' +
+    Object.keys(inputCounts)
+      .map((k) => `${k}=${inputCounts[k]}`)
+      .join(', '),
+)
+
+const e = provider.entries('getpath', 'basic')[0]
+console.log(
+  'getpath/basic[0]: id=' +
+    e.id +
+    ', doc=' +
+    e.doc +
+    ', input.kind=' +
+    e.input.kind +
+    ', expect.kind=' +
+    e.expect.kind +
+    ', expect.value=' +
+    JSON.stringify(e.expect.value),
+)
diff --git a/test/proto/kotlin/Provider.kt b/test/proto/kotlin/Provider.kt
new file mode 100644
index 0000000..a405e57
--- /dev/null
+++ b/test/proto/kotlin/Provider.kt
@@ -0,0 +1,727 @@
+// Test Provider (prototype) — Kotlin (JVM) port of the canonical ts/provider.ts.
+//
+// Reads the shared corpus (build/test/test.json) and hands test code clean,
+// normalized cases. It is NOT a test runner: it never calls the subject and
+// never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+//
+// DEPENDENCY-FREE: Kotlin/Java standard library only. The JVM has no stdlib
+// JSON, so this file bundles its own minimal parser (see object Json). No
+// kotlinx.serialization, no Gson, no Jackson.
+
+package voxgig.struct.proto
+
+import java.nio.charset.StandardCharsets
+import java.nio.file.Files
+import java.nio.file.Paths
+
+// ─── minimal JSON parser ─────────────────────────────────────────────────────
+//
+// Parses into JVM object trees that preserve insertion order:
+//   objects     -> LinkedHashMap<String, Any?>  (PRESERVES key order)
+//   arrays      -> ArrayList<Any?>
+//   strings     -> String
+//   numbers     -> Double
+//   true/false  -> Boolean
+//   null        -> null
+object Json {
+    class JsonException(msg: String) : RuntimeException(msg)
+
+    fun parse(text: String): Any? {
+        val p = Parser(text)
+        p.skipWs()
+        val v = p.parseValue()
+        p.skipWs()
+        if (!p.atEnd()) {
+            throw JsonException("Trailing content at position ${p.pos}")
+        }
+        return v
+    }
+
+    private class Parser(val s: String) {
+        var pos: Int = 0
+
+        fun atEnd(): Boolean = pos >= s.length
+
+        fun skipWs() {
+            while (pos < s.length) {
+                val c = s[pos]
+                if (c == ' ' || c == '\t' || c == '\n' || c == '\r') {
+                    pos++
+                } else {
+                    break
+                }
+            }
+        }
+
+        fun peek(): Char {
+            if (pos >= s.length) {
+                throw JsonException("Unexpected end of input")
+            }
+            return s[pos]
+        }
+
+        fun parseValue(): Any? {
+            skipWs()
+            val c = peek()
+            return when (c) {
+                '{' -> parseObject()
+                '[' -> parseArray()
+                '"' -> parseString()
+                't', 'f' -> parseBool()
+                'n' -> parseNull()
+                else -> {
+                    if (c == '-' || (c in '0'..'9')) {
+                        parseNumber()
+                    } else {
+                        throw JsonException("Unexpected char '$c' at position $pos")
+                    }
+                }
+            }
+        }
+
+        fun parseObject(): LinkedHashMap<String, Any?> {
+            val m = LinkedHashMap<String, Any?>()
+            pos++ // consume '{'
+            skipWs()
+            if (peek() == '}') {
+                pos++
+                return m
+            }
+            while (true) {
+                skipWs()
+                if (peek() != '"') {
+                    throw JsonException("Expected string key at position $pos")
+                }
+                val key = parseString()
+                skipWs()
+                if (peek() != ':') {
+                    throw JsonException("Expected ':' at position $pos")
+                }
+                pos++ // consume ':'
+                val v = parseValue()
+                m[key] = v
+                skipWs()
+                val c = peek()
+                if (c == ',') {
+                    pos++
+                    continue
+                }
+                if (c == '}') {
+                    pos++
+                    break
+                }
+                throw JsonException("Expected ',' or '}' at position $pos")
+            }
+            return m
+        }
+
+        fun parseArray(): ArrayList<Any?> {
+            val list = ArrayList<Any?>()
+            pos++ // consume '['
+            skipWs()
+            if (peek() == ']') {
+                pos++
+                return list
+            }
+            while (true) {
+                val v = parseValue()
+                list.add(v)
+                skipWs()
+                val c = peek()
+                if (c == ',') {
+                    pos++
+                    continue
+                }
+                if (c == ']') {
+                    pos++
+                    break
+                }
+                throw JsonException("Expected ',' or ']' at position $pos")
+            }
+            return list
+        }
+
+        fun parseString(): String {
+            pos++ // consume opening '"'
+            val sb = StringBuilder()
+            while (true) {
+                if (pos >= s.length) {
+                    throw JsonException("Unterminated string")
+                }
+                val c = s[pos++]
+                if (c == '"') {
+                    break
+                }
+                if (c == '\\') {
+                    if (pos >= s.length) {
+                        throw JsonException("Unterminated escape")
+                    }
+                    val e = s[pos++]
+                    when (e) {
+                        '"' -> sb.append('"')
+                        '\\' -> sb.append('\\')
+                        '/' -> sb.append('/')
+                        'b' -> sb.append('\b')
+                        'f' -> sb.append('\u000C')
+                        'n' -> sb.append('\n')
+                        'r' -> sb.append('\r')
+                        't' -> sb.append('\t')
+                        'u' -> {
+                            if (pos + 4 > s.length) {
+                                throw JsonException("Invalid \\u escape")
+                            }
+                            val hex = s.substring(pos, pos + 4)
+                            pos += 4
+                            try {
+                                sb.append(hex.toInt(16).toChar())
+                            } catch (nfe: NumberFormatException) {
+                                throw JsonException("Invalid \\u escape: $hex")
+                            }
+                        }
+                        else -> throw JsonException("Invalid escape '\\$e'")
+                    }
+                } else {
+                    sb.append(c)
+                }
+            }
+            return sb.toString()
+        }
+
+        fun parseBool(): Boolean {
+            if (s.startsWith("true", pos)) {
+                pos += 4
+                return true
+            }
+            if (s.startsWith("false", pos)) {
+                pos += 5
+                return false
+            }
+            throw JsonException("Invalid literal at position $pos")
+        }
+
+        fun parseNull(): Any? {
+            if (s.startsWith("null", pos)) {
+                pos += 4
+                return null
+            }
+            throw JsonException("Invalid literal at position $pos")
+        }
+
+        fun parseNumber(): Double {
+            val start = pos
+            if (peek() == '-') {
+                pos++
+            }
+            while (pos < s.length && s[pos].isDigit()) {
+                pos++
+            }
+            if (pos < s.length && s[pos] == '.') {
+                pos++
+                while (pos < s.length && s[pos].isDigit()) {
+                    pos++
+                }
+            }
+            if (pos < s.length && (s[pos] == 'e' || s[pos] == 'E')) {
+                pos++
+                if (pos < s.length && (s[pos] == '+' || s[pos] == '-')) {
+                    pos++
+                }
+                while (pos < s.length && s[pos].isDigit()) {
+                    pos++
+                }
+            }
+            val num = s.substring(start, pos)
+            try {
+                return num.toDouble()
+            } catch (nfe: NumberFormatException) {
+                throw JsonException("Invalid number '$num'")
+            }
+        }
+    }
+
+    // ─── serialization ───────────────────────────────────────────────────────
+    //
+    // Compact JSON. Whole-number Doubles render without a trailing ".0"
+    // (so 42.0 -> "42"), matching the canonical stringify expectations.
+    fun stringify(v: Any?): String {
+        val sb = StringBuilder()
+        write(v, sb)
+        return sb.toString()
+    }
+
+    private fun write(v: Any?, sb: StringBuilder) {
+        when (v) {
+            null -> sb.append("null")
+            is String -> writeString(v, sb)
+            is Double -> writeNumber(v, sb)
+            is Number -> writeNumber(v.toDouble(), sb)
+            is Boolean -> sb.append(if (v) "true" else "false")
+            is Map<*, *> -> {
+                sb.append('{')
+                var first = true
+                for ((k, value) in v) {
+                    if (!first) sb.append(',')
+                    first = false
+                    writeString(k.toString(), sb)
+                    sb.append(':')
+                    write(value, sb)
+                }
+                sb.append('}')
+            }
+            is List<*> -> {
+                sb.append('[')
+                var first = true
+                for (x in v) {
+                    if (!first) sb.append(',')
+                    first = false
+                    write(x, sb)
+                }
+                sb.append(']')
+            }
+            else -> writeString(v.toString(), sb)
+        }
+    }
+
+    private fun writeNumber(d: Double, sb: StringBuilder) {
+        if (d.isFinite() && Math.floor(d) == d && Math.abs(d) < 1e15) {
+            sb.append(d.toLong().toString())
+        } else {
+            sb.append(d.toString())
+        }
+    }
+
+    private fun writeString(s: String, sb: StringBuilder) {
+        sb.append('"')
+        for (c in s) {
+            when (c) {
+                '"' -> sb.append("\\\"")
+                '\\' -> sb.append("\\\\")
+                '\b' -> sb.append("\\b")
+                '\u000C' -> sb.append("\\f")
+                '\n' -> sb.append("\\n")
+                '\r' -> sb.append("\\r")
+                '\t' -> sb.append("\\t")
+                else -> {
+                    if (c < ' ') {
+                        sb.append("\\u%04x".format(c.code))
+                    } else {
+                        sb.append(c)
+                    }
+                }
+            }
+        }
+        sb.append('"')
+    }
+}
+
+// ─── normalized records ──────────────────────────────────────────────────────
+
+enum class InputKind { IN, ARGS, CTX }
+
+enum class ExpectKind { VALUE, ERROR, MATCH, ABSENT }
+
+data class Input(
+    val kind: InputKind,
+    val value: Any?,
+)
+
+data class ErrorCheck(
+    val any: Boolean,
+    val text: String?,
+    val regex: Boolean,
+)
+
+data class Expect(
+    val kind: ExpectKind,
+    val hasValue: Boolean,
+    val value: Any?,
+    val error: ErrorCheck?,
+    val match: Any?,
+)
+
+data class Entry(
+    val function: String,
+    val group: String,
+    val index: Int,
+    val id: String?,
+    val doc: Boolean,
+    val client: String?,
+    val input: Input,
+    val expect: Expect,
+    val raw: Any?,
+)
+
+data class MatchResult(
+    val ok: Boolean,
+    val path: List<String>? = null,
+    val expected: Any? = null,
+    val actual: Any? = null,
+)
+
+// ─── provider ────────────────────────────────────────────────────────────────
+
+class TestProvider(private val spec: Any?) {
+    companion object {
+        const val NULLMARK = "__NULL__"
+        const val UNDEFMARK = "__UNDEF__"
+        const val EXISTSMARK = "__EXISTS__"
+
+        // Default corpus path resolves to build/test/test.json relative to the
+        // process working directory (mirrors the Java port). A non-null path is
+        // used as-is, so callers may pass an absolute or repo-relative path.
+        fun load(path: String? = null): TestProvider {
+            val file = path ?: defaultTestFile()
+            val json = String(Files.readAllBytes(Paths.get(file)), StandardCharsets.UTF_8)
+            return TestProvider(Json.parse(json))
+        }
+
+        private fun defaultTestFile(): String {
+            val here = Paths.get(System.getProperty("user.dir"))
+            return here.resolve(Paths.get("build", "test", "test.json")).toString()
+        }
+    }
+
+    fun raw(): Any? = spec
+
+    @Suppress("UNCHECKED_CAST")
+    private fun root(): Map<String, Any?> {
+        if (spec is Map<*, *>) {
+            val struct = (spec as Map<String, Any?>)["struct"]
+            if (struct is Map<*, *>) {
+                return struct as Map<String, Any?>
+            }
+            return spec as Map<String, Any?>
+        }
+        return LinkedHashMap()
+    }
+
+    @Suppress("UNCHECKED_CAST")
+    private fun fnNode(fn: String): Map<String, Any?> {
+        var node: Any? = null
+        if (spec is Map<*, *>) {
+            val sp = spec as Map<String, Any?>
+            val struct = sp["struct"]
+            if (struct is Map<*, *> && (struct as Map<String, Any?>).containsKey(fn)) {
+                node = (struct as Map<String, Any?>)[fn]
+            } else if (sp.containsKey(fn)) {
+                node = sp[fn]
+            }
+        }
+        if (node == null) {
+            throw IllegalArgumentException("Unknown function: $fn")
+        }
+        return node as Map<String, Any?>
+    }
+
+    fun functions(): List<String> {
+        val out = ArrayList<String>()
+        for ((k, v) in root()) {
+            if (isGroupBag(v) || hasGroups(v)) {
+                out.add(k)
+            }
+        }
+        return out
+    }
+
+    fun groups(fn: String): List<String> {
+        val out = ArrayList<String>()
+        for ((k, v) in fnNode(fn)) {
+            if (k != "name" && isGroupBag(v)) {
+                out.add(k)
+            }
+        }
+        return out
+    }
+
+    // group == null means "all groups for the function".
+    @Suppress("UNCHECKED_CAST")
+    fun entries(fn: String, group: String? = null): List<Entry> {
+        val node = fnNode(fn)
+        val groupList = if (group != null) listOf(group) else groups(fn)
+        val out = ArrayList<Entry>()
+        for (g in groupList) {
+            val bag = node[g]
+            if (!isGroupBag(bag)) {
+                continue
+            }
+            val set = (bag as Map<String, Any?>)["set"] as List<Any?>
+            for (i in set.indices) {
+                out.add(normalize(fn, g, i, set[i] as Map<String, Any?>))
+            }
+        }
+        return out
+    }
+}
+
+// ─── group detection ─────────────────────────────────────────────────────────
+
+// A group bag is a map with a `set` list.
+private fun isGroupBag(v: Any?): Boolean {
+    return v is Map<*, *> && v["set"] is List<*>
+}
+
+// A function node has at least one child group bag.
+private fun hasGroups(v: Any?): Boolean {
+    if (v !is Map<*, *>) {
+        return false
+    }
+    for ((k, value) in v) {
+        if (k != "name" && isGroupBag(value)) {
+            return true
+        }
+    }
+    return false
+}
+
+// ─── normalization ───────────────────────────────────────────────────────────
+
+private fun has(raw: Map<String, Any?>, key: String): Boolean = raw.containsKey(key)
+
+private fun normalize(fn: String, group: String, index: Int, raw: Map<String, Any?>): Entry {
+    val id = raw["id"]
+    val client = raw["client"]
+    return Entry(
+        function = fn,
+        group = group,
+        index = index,
+        id = if (id != null) id.toString() else null,
+        doc = raw["doc"] == true,
+        client = if (client != null) client.toString() else null,
+        input = resolveInput(raw),
+        expect = resolveExpect(raw),
+        raw = raw,
+    )
+}
+
+private fun resolveInput(raw: Map<String, Any?>): Input {
+    // Precedence ctx > args > in (mirrors resolveArgs).
+    if (has(raw, "ctx")) {
+        return Input(InputKind.CTX, raw["ctx"])
+    }
+    if (has(raw, "args")) {
+        return Input(InputKind.ARGS, raw["args"])
+    }
+    // IN: key absent => native null.
+    return Input(InputKind.IN, if (has(raw, "in")) raw["in"] else null)
+}
+
+private fun parseErr(err: Any?): ErrorCheck {
+    if (err == true) {
+        return ErrorCheck(any = true, text = null, regex = false)
+    }
+    if (err is String) {
+        val m = Regex("^/(.+)/$").matchEntire(err)
+        if (m != null) {
+            return ErrorCheck(any = false, text = m.groupValues[1], regex = true)
+        }
+        return ErrorCheck(any = false, text = err, regex = false)
+    }
+    // Non-true, non-string err spec: treat as "any error".
+    return ErrorCheck(any = true, text = null, regex = false)
+}
+
+private fun resolveExpect(raw: Map<String, Any?>): Expect {
+    // Attach match whenever a "match" key exists (even alongside err/out).
+    val matchPart = if (has(raw, "match")) raw["match"] else null
+    // Precedence err > out > match > absent.
+    if (has(raw, "err")) {
+        return Expect(ExpectKind.ERROR, hasValue = false, value = null, error = parseErr(raw["err"]), match = matchPart)
+    }
+    // KEY PRESENCE, not null-check: "out" present even if null => VALUE.
+    if (has(raw, "out")) {
+        return Expect(ExpectKind.VALUE, hasValue = true, value = raw["out"], error = null, match = matchPart)
+    }
+    if (has(raw, "match")) {
+        return Expect(ExpectKind.MATCH, hasValue = false, value = null, error = null, match = raw["match"])
+    }
+    return Expect(ExpectKind.ABSENT, hasValue = false, value = null, error = null, match = null)
+}
+
+// ─── pure comparison helpers ─────────────────────────────────────────────────
+
+// Sentinel distinguishing "key absent" from "value is null" in getpath.
+private val MISSING = Any()
+
+// stringify(x) = x if it is already a String, else compact JSON.
+fun stringify(x: Any?): String = if (x is String) x else Json.stringify(x)
+
+private fun normNull(x: Any?): Any? {
+    if (x == TestProvider.NULLMARK || x == null) {
+        return null
+    }
+    if (x is List<*>) {
+        return x.map { normNull(it) }
+    }
+    if (x is Map<*, *>) {
+        val out = LinkedHashMap<String, Any?>()
+        for ((k, v) in x) {
+            out[k.toString()] = normNull(v)
+        }
+        return out
+    }
+    return x
+}
+
+private fun normMark(x: Any?): Any? {
+    if (x == TestProvider.NULLMARK) {
+        return null
+    }
+    if (x is List<*>) {
+        return x.map { normMark(it) }
+    }
+    if (x is Map<*, *>) {
+        val out = LinkedHashMap<String, Any?>()
+        for ((k, v) in x) {
+            out[k.toString()] = normMark(v)
+        }
+        return out
+    }
+    return x
+}
+
+// Scalar identity mirroring JS ===: distinguishes Boolean from Number, and
+// compares numbers/strings/booleans by value.
+private fun scalarEq(a: Any?, b: Any?): Boolean {
+    if (a === b) {
+        return true
+    }
+    if (a == null || b == null) {
+        return false
+    }
+    if ((a is Boolean) != (b is Boolean)) {
+        return false
+    }
+    if (a is Number && b is Number) {
+        return a.toDouble() == b.toDouble()
+    }
+    return a == b
+}
+
+fun matchval(check: Any?, base: Any?): Boolean {
+    if (scalarEq(check, base)) {
+        return true
+    }
+    if (check is String) {
+        val basestr = stringify(base)
+        val rem = Regex("^/(.+)/$").matchEntire(check)
+        if (rem != null) {
+            return Regex(rem.groupValues[1]).containsMatchIn(basestr)
+        }
+        return basestr.lowercase().contains(check.lowercase())
+    }
+    // A "function" check (not representable from JSON) would return true; no
+    // such value arises from the parsed corpus.
+    return false
+}
+
+fun equal(expected: Any?, actual: Any?): Boolean = deepEq(normNull(expected), normNull(actual))
+
+// Strict variant for the runner's { null: false } functions, where an absent
+// value is distinct from JSON null. Only __NULL__ is normalized.
+fun equalStrict(expected: Any?, actual: Any?): Boolean = deepEq(normMark(expected), normMark(actual))
+
+private fun deepEq(a: Any?, b: Any?): Boolean {
+    if (a === b) {
+        return true
+    }
+    if (a is List<*> && b is List<*>) {
+        if (a.size != b.size) {
+            return false
+        }
+        for (i in a.indices) {
+            if (!deepEq(a[i], b[i])) {
+                return false
+            }
+        }
+        return true
+    }
+    if (a is List<*> || b is List<*>) {
+        return false
+    }
+    if (a is Map<*, *> && b is Map<*, *>) {
+        if (a.size != b.size) {
+            return false
+        }
+        for ((k, v) in a) {
+            if (!b.containsKey(k) || !deepEq(v, b[k])) {
+                return false
+            }
+        }
+        return true
+    }
+    if (a is Map<*, *> || b is Map<*, *>) {
+        return false
+    }
+    return scalarEq(a, b)
+}
+
+fun errorMatches(check: ErrorCheck, message: String): Boolean {
+    if (check.any) {
+        return true
+    }
+    if (check.text == null) {
+        return false
+    }
+    if (check.regex) {
+        return Regex(check.text).containsMatchIn(message)
+    }
+    return message.lowercase().contains(check.text.lowercase())
+}
+
+// Partial structural match: every leaf of `check` must match `base` at its path.
+fun structMatch(check: Any?, base: Any?): MatchResult {
+    var result = MatchResult(ok = true)
+    walkLeaves(check, ArrayList()) { value, path ->
+        if (!result.ok) {
+            return@walkLeaves
+        }
+        val baseval = getpath(base, path)
+        if (baseval !== MISSING && scalarEq(value, baseval)) {
+            return@walkLeaves
+        }
+        if (TestProvider.UNDEFMARK == value && baseval === MISSING) {
+            return@walkLeaves
+        }
+        if (TestProvider.EXISTSMARK == value && baseval !== MISSING && baseval != null) {
+            return@walkLeaves
+        }
+        val compareBase = if (baseval === MISSING) null else baseval
+        if (!matchval(value, compareBase)) {
+            result = MatchResult(ok = false, path = path, expected = value, actual = compareBase)
+        }
+    }
+    return result
+}
+
+private fun walkLeaves(node: Any?, path: List<String>, fn: (Any?, List<String>) -> Unit) {
+    if (node is List<*>) {
+        for (i in node.indices) {
+            walkLeaves(node[i], path + i.toString(), fn)
+        }
+    } else if (node is Map<*, *>) {
+        for ((k, v) in node) {
+            walkLeaves(v, path + k.toString(), fn)
+        }
+    } else {
+        fn(node, path)
+    }
+}
+
+// Returns MISSING for an absent path (distinct from a present null).
+private fun getpath(store: Any?, path: List<String>): Any? {
+    var cur: Any? = store
+    for (key in path) {
+        if (cur == null || cur === MISSING) {
+            return MISSING
+        }
+        cur = when (cur) {
+            is List<*> -> {
+                val idx = key.toIntOrNull() ?: return MISSING
+                if (idx >= 0 && idx < cur.size) cur[idx] else MISSING
+            }
+            is Map<*, *> -> if (cur.containsKey(key)) cur[key] else MISSING
+            else -> return MISSING
+        }
+    }
+    return cur
+}
diff --git a/test/proto/kotlin/Smoke.kt b/test/proto/kotlin/Smoke.kt
new file mode 100644
index 0000000..b09c789
--- /dev/null
+++ b/test/proto/kotlin/Smoke.kt
@@ -0,0 +1,65 @@
+// Smoke harness for the Kotlin test provider port. Prints summary stats that
+// must match the canonical TS output documented in PROVIDER.md.
+//
+// Run (from the repo root, once a Kotlin toolchain is available), e.g.:
+//   kotlinc test/proto/kotlin/Provider.kt test/proto/kotlin/Smoke.kt -include-runtime -d /tmp/proto.jar
+//   java -jar /tmp/proto.jar
+// The default corpus path resolves to build/test/test.json relative to the
+// process working directory.
+
+package voxgig.struct.proto
+
+fun main() {
+    val prov = TestProvider.load()
+
+    val fns = prov.functions()
+    println("functions: " + fns.joinToString(", "))
+
+    var total = 0
+    val expectKinds = LinkedHashMap<String, Int>()
+    val inputKinds = LinkedHashMap<String, Int>()
+    for (fn in fns) {
+        for (entry in prov.entries(fn)) {
+            total++
+            val ek = entry.expect.kind.name.lowercase()
+            val ik = entry.input.kind.name.lowercase()
+            expectKinds[ek] = (expectKinds[ek] ?: 0) + 1
+            inputKinds[ik] = (inputKinds[ik] ?: 0) + 1
+        }
+    }
+
+    println("total entries: $total")
+    println(
+        "expect kinds: " +
+            expectKinds.keys.sorted().joinToString(", ") { "$it=${expectKinds[it]}" },
+    )
+    println(
+        "input kinds: " +
+            inputKinds.keys.sorted().joinToString(", ") { "$it=${inputKinds[it]}" },
+    )
+
+    val e = prov.entries("getpath", "basic")[0]
+    println(
+        "getpath/basic[0]: " +
+            "id=${e.id}, doc=${e.doc}, " +
+            "input.kind=${e.input.kind.name.lowercase()}, " +
+            "expect.kind=${e.expect.kind.name.lowercase()}, " +
+            "expect.value=${stringify(e.expect.value)}",
+    )
+
+    // ─── helper sanity checks ──────────────────────────────────────────────
+    println("equal(null, absent) lenient: " + equal(null, null))
+    println(
+        "equalStrict distinguishes null vs __NULL__-collapse: " +
+            equalStrict(null, TestProvider.NULLMARK) + " / " + equalStrict(null, 1.0),
+    )
+    println(
+        "errorMatches substring case-insensitive: " +
+            errorMatches(ErrorCheck(any = false, text = "Foo", regex = false), "a foobar error"),
+    )
+    val sm = structMatch(
+        linkedMapOf("a" to linkedMapOf("b" to 2.0)),
+        linkedMapOf("a" to linkedMapOf("b" to 3.0)),
+    )
+    println("structMatch failure: ok=${sm.ok}, path=${sm.path}, expected=${sm.expected}, actual=${sm.actual}")
+}
diff --git a/test/proto/lua/provider.lua b/test/proto/lua/provider.lua
new file mode 100644
index 0000000..f667a64
--- /dev/null
+++ b/test/proto/lua/provider.lua
@@ -0,0 +1,1030 @@
+-- Test Provider (prototype) — Lua (5.3/5.4) port of the canonical ts/provider.ts.
+--
+-- Reads the shared corpus (build/test/test.json) and hands test code clean,
+-- normalized cases. It is NOT a test runner: it never calls the subject and
+-- never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+--
+-- DEPENDENCY-FREE: no dkjson, no lfs, no LuaRocks deps. The JSON parser below
+-- is a self-contained pure-Lua recursive-descent parser; files are read with
+-- io.open.
+--
+-- Data model note (the crux of the port):
+--   Lua tables cannot preserve insertion order for string keys, and cannot
+--   store nil as a value. JSON ordering matters here (functions()/groups()
+--   enumerate keys in corpus order) and JSON null must stay distinct from
+--   "key absent". So we represent parsed JSON as:
+--     * OBJECT -> { __obj = true, keys = {ordered key list}, map = {k = v} }
+--     * ARRAY  -> { __arr = true, items = {1-based value list} }
+--     * null   -> the unique sentinel table JSON_NULL
+--     * string/number/boolean -> native Lua values
+--   Key PRESENCE is tested via the object's map (a key can be present with a
+--   JSON_NULL value), never via truthiness.
+
+local M = {}
+
+local NULLMARK = "__NULL__" -- Value is JSON null
+local UNDEFMARK = "__UNDEF__" -- Value is not present (thus undefined)
+local EXISTSMARK = "__EXISTS__" -- Value exists (not undefined)
+
+-- Unique sentinel for JSON null (distinguishes from absent and from the
+-- literal string "null").
+local JSON_NULL = setmetatable({}, {
+  __tostring = function()
+    return "null"
+  end,
+})
+
+-- Unique sentinel meaning "no value at this path" (mirrors TS undefined /
+-- Python _MISSING). Distinct from JSON_NULL.
+local MISSING = setmetatable({}, {
+  __tostring = function()
+    return "<missing>"
+  end,
+})
+
+M.NULLMARK = NULLMARK
+M.UNDEFMARK = UNDEFMARK
+M.EXISTSMARK = EXISTSMARK
+M.JSON_NULL = JSON_NULL
+M.MISSING = MISSING
+
+----------------------------------------------------------
+-- Object / array helpers (our ordered-object representation)
+----------------------------------------------------------
+
+local function is_obj(v)
+  return type(v) == "table" and v.__obj == true
+end
+
+local function is_arr(v)
+  return type(v) == "table" and v.__arr == true
+end
+
+-- Is `v` a "node" (object or array), i.e. a recursable container?
+local function is_node(v)
+  return is_obj(v) or is_arr(v)
+end
+
+local function new_obj()
+  return { __obj = true, keys = {}, map = {} }
+end
+
+local function new_arr()
+  return { __arr = true, items = {} }
+end
+
+-- Does an object have `key` present (even if its value is JSON_NULL)?
+local function obj_has(o, key)
+  if not is_obj(o) then
+    return false
+  end
+  -- map cannot store nil values, but JSON null is stored as JSON_NULL, so a
+  -- present key always has a non-nil map entry. Still, guard via keys list to
+  -- be unambiguous.
+  for _, k in ipairs(o.keys) do
+    if k == key then
+      return true
+    end
+  end
+  return false
+end
+
+-- Get an object's value for `key`; returns MISSING if the key is absent.
+local function obj_get(o, key)
+  if is_obj(o) and obj_has(o, key) then
+    return o.map[key]
+  end
+  return MISSING
+end
+
+-- Set an object's key/value, appending the key if new (preserving order).
+local function obj_set(o, key, value)
+  if not obj_has(o, key) then
+    table.insert(o.keys, key)
+  end
+  o.map[key] = value
+end
+
+M.is_obj = is_obj
+M.is_arr = is_arr
+M.is_node = is_node
+M.obj_has = obj_has
+M.obj_get = obj_get
+
+----------------------------------------------------------
+-- Pure-Lua recursive-descent JSON parser
+----------------------------------------------------------
+-- Handles: objects (order preserved), arrays, strings (with \uXXXX, surrogate
+-- pairs, and standard escapes), numbers (negative, fractional, exponents),
+-- true/false/null, and surrounding whitespace.
+
+local json_parse_value -- forward decl
+
+-- Parse error helper.
+local function jerror(str, pos, msg)
+  -- Compute a 1-based line/col for a friendlier message.
+  local line, col = 1, 1
+  for i = 1, pos - 1 do
+    if str:sub(i, i) == "\n" then
+      line = line + 1
+      col = 1
+    else
+      col = col + 1
+    end
+  end
+  error(string.format("JSON parse error at line %d col %d (byte %d): %s", line, col, pos, msg), 0)
+end
+
+local function is_ws(c)
+  return c == " " or c == "\t" or c == "\n" or c == "\r"
+end
+
+-- Skip whitespace, returning the next significant position.
+local function skip_ws(str, pos)
+  local len = #str
+  while pos <= len and is_ws(str:sub(pos, pos)) do
+    pos = pos + 1
+  end
+  return pos
+end
+
+-- Encode a Unicode code point as UTF-8 (pure Lua; no utf8 library reliance,
+-- though Lua 5.3+ has utf8.char — we implement directly for clarity/safety).
+local function utf8_encode(cp)
+  if cp < 0x80 then
+    return string.char(cp)
+  elseif cp < 0x800 then
+    return string.char(
+      0xC0 + math.floor(cp / 0x40),
+      0x80 + (cp % 0x40)
+    )
+  elseif cp < 0x10000 then
+    return string.char(
+      0xE0 + math.floor(cp / 0x1000),
+      0x80 + (math.floor(cp / 0x40) % 0x40),
+      0x80 + (cp % 0x40)
+    )
+  else
+    return string.char(
+      0xF0 + math.floor(cp / 0x40000),
+      0x80 + (math.floor(cp / 0x1000) % 0x40),
+      0x80 + (math.floor(cp / 0x40) % 0x40),
+      0x80 + (cp % 0x40)
+    )
+  end
+end
+
+local ESCAPES = {
+  ['"'] = '"',
+  ["\\"] = "\\",
+  ["/"] = "/",
+  ["b"] = "\b",
+  ["f"] = "\f",
+  ["n"] = "\n",
+  ["r"] = "\r",
+  ["t"] = "\t",
+}
+
+local function parse_hex4(str, pos)
+  local hex = str:sub(pos, pos + 3)
+  if #hex < 4 or not hex:match("^%x%x%x%x$") then
+    jerror(str, pos, "invalid \\u escape (expected 4 hex digits)")
+  end
+  return tonumber(hex, 16), pos + 4
+end
+
+-- Parse a JSON string starting at the opening quote.
+-- Returns (string, next_pos).
+local function parse_string(str, pos)
+  -- str:sub(pos,pos) == '"'
+  pos = pos + 1
+  local parts = {}
+  local len = #str
+  while pos <= len do
+    local c = str:sub(pos, pos)
+    if c == '"' then
+      return table.concat(parts), pos + 1
+    elseif c == "\\" then
+      pos = pos + 1
+      local e = str:sub(pos, pos)
+      if e == "u" then
+        local cp
+        cp, pos = parse_hex4(str, pos + 1)
+        -- Handle UTF-16 surrogate pairs.
+        if cp >= 0xD800 and cp <= 0xDBFF then
+          if str:sub(pos, pos + 1) == "\\u" then
+            local lo
+            lo, pos = parse_hex4(str, pos + 2)
+            if lo >= 0xDC00 and lo <= 0xDFFF then
+              cp = 0x10000 + (cp - 0xD800) * 0x400 + (lo - 0xDC00)
+            else
+              -- Unpaired high surrogate followed by a non-low \u escape;
+              -- emit the replacement char then continue with `lo` as its own.
+              parts[#parts + 1] = utf8_encode(0xFFFD)
+              cp = lo
+            end
+          else
+            -- Lone high surrogate.
+            cp = 0xFFFD
+          end
+        elseif cp >= 0xDC00 and cp <= 0xDFFF then
+          -- Lone low surrogate.
+          cp = 0xFFFD
+        end
+        parts[#parts + 1] = utf8_encode(cp)
+      else
+        local mapped = ESCAPES[e]
+        if mapped == nil then
+          jerror(str, pos, "invalid escape \\" .. e)
+        end
+        parts[#parts + 1] = mapped
+        pos = pos + 1
+      end
+    elseif c == "\n" or c == "\r" then
+      jerror(str, pos, "unescaped control character in string")
+    else
+      parts[#parts + 1] = c
+      pos = pos + 1
+    end
+  end
+  jerror(str, pos, "unterminated string")
+end
+
+-- Parse a JSON number starting at `pos`. Returns (number, next_pos).
+-- Grammar: -?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?
+local function parse_number(str, pos)
+  local start = pos
+  local len = #str
+  local c = str:sub(pos, pos)
+
+  if c == "-" then
+    pos = pos + 1
+    c = str:sub(pos, pos)
+  end
+
+  -- Integer part.
+  if c == "0" then
+    pos = pos + 1
+  elseif c:match("%d") then
+    while pos <= len and str:sub(pos, pos):match("%d") do
+      pos = pos + 1
+    end
+  else
+    jerror(str, pos, "invalid number (expected digit)")
+  end
+
+  -- Fraction.
+  if str:sub(pos, pos) == "." then
+    pos = pos + 1
+    if not str:sub(pos, pos):match("%d") then
+      jerror(str, pos, "invalid number (expected digit after '.')")
+    end
+    while pos <= len and str:sub(pos, pos):match("%d") do
+      pos = pos + 1
+    end
+  end
+
+  -- Exponent.
+  local ec = str:sub(pos, pos)
+  if ec == "e" or ec == "E" then
+    pos = pos + 1
+    local sign = str:sub(pos, pos)
+    if sign == "+" or sign == "-" then
+      pos = pos + 1
+    end
+    if not str:sub(pos, pos):match("%d") then
+      jerror(str, pos, "invalid number (expected digit in exponent)")
+    end
+    while pos <= len and str:sub(pos, pos):match("%d") do
+      pos = pos + 1
+    end
+  end
+
+  local numstr = str:sub(start, pos - 1)
+  local n = tonumber(numstr)
+  if n == nil then
+    jerror(str, start, "invalid number: " .. numstr)
+  end
+  return n, pos
+end
+
+local function parse_array(str, pos)
+  -- str:sub(pos,pos) == '['
+  pos = pos + 1
+  local arr = new_arr()
+  pos = skip_ws(str, pos)
+  if str:sub(pos, pos) == "]" then
+    return arr, pos + 1
+  end
+  while true do
+    local val
+    val, pos = json_parse_value(str, pos)
+    arr.items[#arr.items + 1] = val
+    pos = skip_ws(str, pos)
+    local c = str:sub(pos, pos)
+    if c == "," then
+      pos = skip_ws(str, pos + 1)
+    elseif c == "]" then
+      return arr, pos + 1
+    else
+      jerror(str, pos, "expected ',' or ']' in array")
+    end
+  end
+end
+
+local function parse_object(str, pos)
+  -- str:sub(pos,pos) == '{'
+  pos = pos + 1
+  local obj = new_obj()
+  pos = skip_ws(str, pos)
+  if str:sub(pos, pos) == "}" then
+    return obj, pos + 1
+  end
+  while true do
+    pos = skip_ws(str, pos)
+    if str:sub(pos, pos) ~= '"' then
+      jerror(str, pos, "expected string key in object")
+    end
+    local key
+    key, pos = parse_string(str, pos)
+    pos = skip_ws(str, pos)
+    if str:sub(pos, pos) ~= ":" then
+      jerror(str, pos, "expected ':' after object key")
+    end
+    pos = skip_ws(str, pos + 1)
+    local val
+    val, pos = json_parse_value(str, pos)
+    -- Preserve insertion order; later duplicate keys overwrite the value but
+    -- keep their original position (mirrors JSON.parse semantics closely
+    -- enough for the corpus, which has no duplicate keys).
+    obj_set(obj, key, val)
+    pos = skip_ws(str, pos)
+    local c = str:sub(pos, pos)
+    if c == "," then
+      pos = pos + 1
+    elseif c == "}" then
+      return obj, pos + 1
+    else
+      jerror(str, pos, "expected ',' or '}' in object")
+    end
+  end
+end
+
+json_parse_value = function(str, pos)
+  pos = skip_ws(str, pos)
+  local c = str:sub(pos, pos)
+  if c == "" then
+    jerror(str, pos, "unexpected end of input")
+  elseif c == "{" then
+    return parse_object(str, pos)
+  elseif c == "[" then
+    return parse_array(str, pos)
+  elseif c == '"' then
+    return parse_string(str, pos)
+  elseif c == "t" then
+    if str:sub(pos, pos + 3) == "true" then
+      return true, pos + 4
+    end
+    jerror(str, pos, "invalid literal (expected 'true')")
+  elseif c == "f" then
+    if str:sub(pos, pos + 4) == "false" then
+      return false, pos + 5
+    end
+    jerror(str, pos, "invalid literal (expected 'false')")
+  elseif c == "n" then
+    if str:sub(pos, pos + 3) == "null" then
+      return JSON_NULL, pos + 4
+    end
+    jerror(str, pos, "invalid literal (expected 'null')")
+  elseif c == "-" or c:match("%d") then
+    return parse_number(str, pos)
+  else
+    jerror(str, pos, "unexpected character '" .. c .. "'")
+  end
+end
+
+-- Public: parse a JSON document string into our representation.
+local function json_decode(str)
+  local val, pos = json_parse_value(str, 1)
+  pos = skip_ws(str, pos)
+  if pos <= #str then
+    jerror(str, pos, "trailing characters after JSON value")
+  end
+  return val
+end
+
+M.json_decode = json_decode
+
+----------------------------------------------------------
+-- Compact JSON serialization (for stringify)
+----------------------------------------------------------
+
+local json_encode -- forward decl
+
+local function encode_string(s)
+  local out = { '"' }
+  for i = 1, #s do
+    local c = s:sub(i, i)
+    local b = c:byte()
+    if c == '"' then
+      out[#out + 1] = '\\"'
+    elseif c == "\\" then
+      out[#out + 1] = "\\\\"
+    elseif c == "\n" then
+      out[#out + 1] = "\\n"
+    elseif c == "\r" then
+      out[#out + 1] = "\\r"
+    elseif c == "\t" then
+      out[#out + 1] = "\\t"
+    elseif c == "\b" then
+      out[#out + 1] = "\\b"
+    elseif c == "\f" then
+      out[#out + 1] = "\\f"
+    elseif b < 0x20 then
+      out[#out + 1] = string.format("\\u%04x", b)
+    else
+      out[#out + 1] = c
+    end
+  end
+  out[#out + 1] = '"'
+  return table.concat(out)
+end
+
+-- Format a number like JSON would (integers without trailing ".0").
+local function encode_number(n)
+  if n ~= n then
+    return "null" -- NaN -> null (JSON has no NaN)
+  end
+  if n == math.huge or n == -math.huge then
+    return "null"
+  end
+  if math.type then
+    if math.type(n) == "integer" then
+      return string.format("%d", n)
+    end
+  elseif n == math.floor(n) and math.abs(n) < 1e15 then
+    return string.format("%d", n)
+  end
+  -- Float: use %.17g then strip, but %.14g is closer to JS for most corpus
+  -- values. Prefer integer-looking floats to print without a fraction.
+  if n == math.floor(n) and math.abs(n) < 1e15 then
+    return string.format("%d", math.floor(n))
+  end
+  return string.format("%.17g", n)
+end
+
+json_encode = function(v)
+  if v == JSON_NULL or v == nil then
+    return "null"
+  elseif v == MISSING then
+    return "null"
+  elseif type(v) == "boolean" then
+    return v and "true" or "false"
+  elseif type(v) == "number" then
+    return encode_number(v)
+  elseif type(v) == "string" then
+    return encode_string(v)
+  elseif is_arr(v) then
+    local parts = {}
+    for i = 1, #v.items do
+      parts[i] = json_encode(v.items[i])
+    end
+    return "[" .. table.concat(parts, ",") .. "]"
+  elseif is_obj(v) then
+    local parts = {}
+    for _, k in ipairs(v.keys) do
+      parts[#parts + 1] = encode_string(k) .. ":" .. json_encode(v.map[k])
+    end
+    return "{" .. table.concat(parts, ",") .. "}"
+  else
+    -- Fallback for unexpected native tables/functions.
+    return "null"
+  end
+end
+
+M.json_encode = json_encode
+
+----------------------------------------------------------
+-- File IO
+----------------------------------------------------------
+
+local function read_file(path)
+  local file = io.open(path, "r")
+  if not file then
+    error("Cannot open file: " .. path, 0)
+  end
+  local content = file:read("*a")
+  file:close()
+  return content
+end
+
+-- Directory of THIS script (provider.lua), used to resolve the default corpus
+-- path relative to the source location rather than the cwd.
+local function script_dir()
+  local src = debug.getinfo(1, "S").source
+  if src:sub(1, 1) == "@" then
+    src = src:sub(2)
+  end
+  local dir = src:match("^(.*)[/\\][^/\\]*$")
+  return dir or "."
+end
+
+-- Default corpus path: build/test/test.json relative to the repo root
+-- (test/proto/lua -> ../../../build/test/test.json).
+local function default_test_file()
+  return script_dir() .. "/../../../build/test/test.json"
+end
+
+M.default_test_file = default_test_file
+
+----------------------------------------------------------
+-- Normalization helpers
+----------------------------------------------------------
+
+-- A group bag is an object with a `set` array.
+local function is_group_bag(v)
+  if not is_obj(v) then
+    return false
+  end
+  return is_arr(obj_get(v, "set"))
+end
+
+-- A function node has at least one child group bag (excluding `name`).
+local function has_groups(v)
+  if not is_obj(v) then
+    return false
+  end
+  for _, k in ipairs(v.keys) do
+    if k ~= "name" and is_group_bag(v.map[k]) then
+      return true
+    end
+  end
+  return false
+end
+
+-- A raw scalar -> "value present?" Uses obj_has so JSON_NULL counts present.
+local function raw_has(raw, key)
+  return obj_has(raw, key)
+end
+
+local function raw_get(raw, key)
+  return obj_get(raw, key)
+end
+
+-- Convert MISSING -> nil for fields where absence should read as nil.
+local function or_nil(v)
+  if v == MISSING then
+    return nil
+  end
+  return v
+end
+
+local function resolve_input(raw)
+  if raw_has(raw, "ctx") then
+    return { kind = "ctx", ctx = or_nil(raw_get(raw, "ctx")) }
+  end
+  if raw_has(raw, "args") then
+    return { kind = "args", args = or_nil(raw_get(raw, "args")) }
+  end
+  -- kind == in. Key absent => native null (JSON_NULL sentinel, matching the
+  -- runner's "absent in => null" treatment while staying distinct from a
+  -- present JSON null, which is also JSON_NULL here).
+  if raw_has(raw, "in") then
+    return { kind = "in", ["in"] = raw_get(raw, "in") }
+  end
+  return { kind = "in", ["in"] = JSON_NULL }
+end
+
+local function parse_err(err)
+  if err == true then
+    return { any = true, text = nil, regex = false }
+  end
+  if type(err) == "string" then
+    local inner = err:match("^/(.+)/$")
+    if inner then
+      return { any = false, text = inner, regex = true }
+    end
+    return { any = false, text = err, regex = false }
+  end
+  -- Non-true, non-string err spec: treat as "any error".
+  return { any = true, text = nil, regex = false }
+end
+
+local function resolve_expect(raw)
+  local match_part = nil
+  if raw_has(raw, "match") then
+    match_part = raw_get(raw, "match")
+  end
+  if raw_has(raw, "err") then
+    return { kind = "error", error = parse_err(raw_get(raw, "err")), match = match_part }
+  end
+  -- KEY PRESENCE: "out" present even if its value is JSON_NULL => VALUE.
+  if raw_has(raw, "out") then
+    return { kind = "value", value = raw_get(raw, "out"), match = match_part }
+  end
+  if raw_has(raw, "match") then
+    return { kind = "match", match = raw_get(raw, "match") }
+  end
+  return { kind = "absent" }
+end
+
+-- Coerce a raw value to a string id/client (only strings expected in corpus).
+local function as_string(v)
+  if v == nil or v == MISSING or v == JSON_NULL then
+    return nil
+  end
+  if type(v) == "string" then
+    return v
+  end
+  if type(v) == "number" or type(v) == "boolean" then
+    return tostring(v)
+  end
+  return nil
+end
+
+local function normalize(fn, group, index, raw)
+  local id_v = raw_has(raw, "id") and raw_get(raw, "id") or nil
+  local client_v = raw_has(raw, "client") and raw_get(raw, "client") or nil
+  local doc_v = raw_has(raw, "doc") and raw_get(raw, "doc") or nil
+  return {
+    ["function"] = fn,
+    group = group,
+    index = index,
+    id = as_string(id_v),
+    doc = (doc_v == true),
+    client = as_string(client_v),
+    input = resolve_input(raw),
+    expect = resolve_expect(raw),
+    raw = raw,
+  }
+end
+
+----------------------------------------------------------
+-- TestProvider
+----------------------------------------------------------
+
+local Provider = {}
+Provider.__index = Provider
+
+-- Resolve the root that holds the function nodes (spec.struct or spec).
+local function root_node(spec)
+  if is_obj(spec) then
+    local s = obj_get(spec, "struct")
+    if is_obj(s) then
+      return s
+    end
+  end
+  return spec
+end
+
+function Provider:raw()
+  return self.spec
+end
+
+function Provider:_fn_node(fn)
+  local node = MISSING
+  if is_obj(self.spec) then
+    local s = obj_get(self.spec, "struct")
+    if is_obj(s) and obj_has(s, fn) then
+      node = obj_get(s, fn)
+    elseif obj_has(self.spec, fn) then
+      node = obj_get(self.spec, fn)
+    end
+  end
+  if node == MISSING or node == nil or node == JSON_NULL then
+    error("Unknown function: " .. tostring(fn), 0)
+  end
+  return node
+end
+
+function Provider:functions()
+  local root = root_node(self.spec)
+  local out = {}
+  if is_obj(root) then
+    for _, k in ipairs(root.keys) do
+      local v = root.map[k]
+      if is_group_bag(v) or has_groups(v) then
+        out[#out + 1] = k
+      end
+    end
+  end
+  return out
+end
+
+function Provider:groups(fn)
+  local node = self:_fn_node(fn)
+  local out = {}
+  if is_obj(node) then
+    for _, k in ipairs(node.keys) do
+      if k ~= "name" and is_group_bag(node.map[k]) then
+        out[#out + 1] = k
+      end
+    end
+  end
+  return out
+end
+
+function Provider:entries(fn, group)
+  local node = self:_fn_node(fn)
+  local groups
+  if group ~= nil then
+    groups = { group }
+  else
+    groups = self:groups(fn)
+  end
+  local out = {}
+  for _, g in ipairs(groups) do
+    local bag = obj_get(node, g)
+    if is_group_bag(bag) then
+      local set = obj_get(bag, "set")
+      local items = set.items
+      for i = 1, #items do
+        -- index is 0-based to match the canonical ports (TS/Python use 0-based
+        -- position within the group's set[]).
+        out[#out + 1] = normalize(fn, g, i - 1, items[i])
+      end
+    end
+  end
+  return out
+end
+
+-- M.load(path): parse test.json and return a provider.
+function M.load(testfile)
+  local file = testfile or default_test_file()
+  local spec = json_decode(read_file(file))
+  return setmetatable({ spec = spec }, Provider)
+end
+
+-- Backwards-friendly alias matching the documented API surface.
+M.TestProvider = { load = M.load }
+
+----------------------------------------------------------
+-- Pure comparison helpers
+----------------------------------------------------------
+
+-- stringify(x) = x if a Lua string, else compact JSON serialization.
+local function stringify(x)
+  if type(x) == "string" then
+    return x
+  end
+  return json_encode(x)
+end
+M.stringify = stringify
+
+-- Normalize NULLMARK / JSON_NULL / nil / MISSING to a single canonical null
+-- token so lenient equality collapses absent ≡ null ≡ __NULL__.
+local NULL_CANON = setmetatable({}, { __tostring = function() return "<null>" end })
+
+local function norm_null(x)
+  if x == NULLMARK or x == nil or x == JSON_NULL or x == MISSING then
+    return NULL_CANON
+  end
+  if is_arr(x) then
+    local r = new_arr()
+    for i = 1, #x.items do
+      r.items[i] = norm_null(x.items[i])
+    end
+    return r
+  end
+  if is_obj(x) then
+    local r = new_obj()
+    for _, k in ipairs(x.keys) do
+      obj_set(r, k, norm_null(x.map[k]))
+    end
+    return r
+  end
+  return x
+end
+
+-- Strict variant: only __NULL__ collapses to null; JSON null stays distinct
+-- from absent. JSON_NULL -> NULL_CANON too (a present JSON null IS null), but
+-- MISSING (absent) stays MISSING.
+local function norm_mark(x)
+  if x == NULLMARK then
+    return NULL_CANON
+  end
+  if x == JSON_NULL then
+    return NULL_CANON
+  end
+  if is_arr(x) then
+    local r = new_arr()
+    for i = 1, #x.items do
+      r.items[i] = norm_mark(x.items[i])
+    end
+    return r
+  end
+  if is_obj(x) then
+    local r = new_obj()
+    for _, k in ipairs(x.keys) do
+      obj_set(r, k, norm_mark(x.map[k]))
+    end
+    return r
+  end
+  return x
+end
+
+-- Deep structural equality over our representation. Arrays compare by length +
+-- element; objects compare by same key set + per-key value. Scalars use ==.
+local function deep_eq(a, b)
+  if a == b then
+    return true
+  end
+  if is_arr(a) and is_arr(b) then
+    if #a.items ~= #b.items then
+      return false
+    end
+    for i = 1, #a.items do
+      if not deep_eq(a.items[i], b.items[i]) then
+        return false
+      end
+    end
+    return true
+  end
+  if is_obj(a) and is_obj(b) then
+    if #a.keys ~= #b.keys then
+      return false
+    end
+    for _, k in ipairs(a.keys) do
+      if not obj_has(b, k) then
+        return false
+      end
+      if not deep_eq(a.map[k], b.map[k]) then
+        return false
+      end
+    end
+    return true
+  end
+  -- One is a container and the other isn't (or scalars unequal).
+  return false
+end
+
+-- matchval(check, base): scalar primitive per PROVIDER.md §5.
+-- check == base; else if check is a string: "/re/" => regex test against
+-- stringify(base); otherwise stringify(base) lowercased CONTAINS check
+-- lowercased (plain substring). Lua has no native regex, so "/re/" uses Lua
+-- patterns. PROTOTYPE: regex simplified — Lua patterns are not JS RegExp.
+local function regex_test(pattern, subject)
+  -- PROTOTYPE: regex simplified. Lua's string.find with a Lua pattern is the
+  -- closest dependency-free approximation to JS new RegExp(re).test(subject).
+  -- It will diverge for JS-specific constructs (alternation |, \d, anchors,
+  -- quantifiers like {n}, etc.). The corpus exercises only one `match`/regex
+  -- error case, kept simple here.
+  local ok, found = pcall(function()
+    return subject:find(pattern) ~= nil
+  end)
+  if not ok then
+    return false
+  end
+  return found
+end
+
+local function matchval(check, base)
+  if check == base then
+    return true
+  end
+  if type(check) == "string" then
+    local basestr = stringify(base)
+    local inner = check:match("^/(.+)/$")
+    if inner then
+      return regex_test(inner, basestr)
+    end
+    -- contains-case: case-insensitive plain substring.
+    return basestr:lower():find(check:lower(), 1, true) ~= nil
+  end
+  if type(check) == "function" then
+    return true
+  end
+  return false
+end
+M.matchval = matchval
+
+-- equal: lenient deep-equal (absent ≡ null ≡ __NULL__).
+local function equal(expected, actual)
+  return deep_eq(norm_null(expected), norm_null(actual))
+end
+M.equal = equal
+
+-- equal_strict: undefined/absent ≠ null; only __NULL__ and JSON null collapse.
+local function equal_strict(expected, actual)
+  return deep_eq(norm_mark(expected), norm_mark(actual))
+end
+M.equal_strict = equal_strict
+
+-- error_matches(check, message): any => true; regex => pattern test; else
+-- case-insensitive plain substring.
+local function error_matches(check, message)
+  if check.any then
+    return true
+  end
+  if check.text == nil then
+    return false
+  end
+  if check.regex then
+    return regex_test(check.text, message)
+  end
+  return message:lower():find(check.text:lower(), 1, true) ~= nil
+end
+M.error_matches = error_matches
+
+-- getpath over our representation. Returns MISSING when the path runs off the
+-- end (mirrors TS undefined / Python _MISSING).
+local function getpath(store, path)
+  local cur = store
+  for _, key in ipairs(path) do
+    if cur == nil or cur == MISSING or cur == JSON_NULL then
+      return MISSING
+    end
+    if is_arr(cur) then
+      local idx = tonumber(key)
+      if idx == nil then
+        return MISSING
+      end
+      -- path indices are 0-based strings; our items are 1-based.
+      cur = cur.items[idx + 1]
+      if cur == nil then
+        return MISSING
+      end
+    elseif is_obj(cur) then
+      if obj_has(cur, key) then
+        cur = cur.map[key]
+      else
+        return MISSING
+      end
+    else
+      return MISSING
+    end
+  end
+  return cur
+end
+M.getpath = getpath
+
+-- Walk every leaf (non-node) of `node`, invoking fn(value, path) with a
+-- string-path list. Mirrors the TS walkLeaves.
+local function walk_leaves(node, path, fn)
+  if is_arr(node) then
+    for i = 1, #node.items do
+      local p = {}
+      for _, x in ipairs(path) do
+        p[#p + 1] = x
+      end
+      p[#p + 1] = tostring(i - 1) -- 0-based index string
+      walk_leaves(node.items[i], p, fn)
+    end
+  elseif is_obj(node) then
+    for _, k in ipairs(node.keys) do
+      local p = {}
+      for _, x in ipairs(path) do
+        p[#p + 1] = x
+      end
+      p[#p + 1] = k
+      walk_leaves(node.map[k], p, fn)
+    end
+  else
+    fn(node, path)
+  end
+end
+
+-- struct_match(check, base) -> { ok, path?, expected?, actual? }
+-- Partial structural match: every leaf of `check` must match `base` at its
+-- path. First failure returns its path + the two values.
+local function struct_match(check, base)
+  local result = { ok = true }
+  walk_leaves(check, {}, function(val, path)
+    if not result.ok then
+      return
+    end
+    local baseval = getpath(base, path)
+
+    -- Direct equality (covers scalars, and JSON_NULL == JSON_NULL).
+    if baseval ~= MISSING and baseval == val then
+      return
+    end
+
+    -- Explicit undefined expected: require absent.
+    if val == UNDEFMARK and baseval == MISSING then
+      return
+    end
+
+    -- Explicit exists expected: require present (and not null).
+    if val == EXISTSMARK and baseval ~= MISSING and baseval ~= JSON_NULL then
+      return
+    end
+
+    local compare_base = baseval
+    if compare_base == MISSING then
+      compare_base = nil
+    end
+    if not matchval(val, compare_base) then
+      result = {
+        ok = false,
+        path = path,
+        expected = val,
+        actual = compare_base,
+      }
+    end
+  end)
+  return result
+end
+M.struct_match = struct_match
+
+return M
diff --git a/test/proto/lua/smoke.lua b/test/proto/lua/smoke.lua
new file mode 100644
index 0000000..b4f33ad
--- /dev/null
+++ b/test/proto/lua/smoke.lua
@@ -0,0 +1,122 @@
+-- Smoke test for the Lua test provider port. Prints summary stats that must
+-- match the canonical TS output documented in PROVIDER.md.
+--
+-- Run from this directory:  lua smoke.lua
+-- (Resolves the corpus relative to provider.lua's source location.)
+
+-- Make `require("provider")` work regardless of cwd by adding this script's
+-- directory to package.path.
+local function this_dir()
+  local src = debug.getinfo(1, "S").source
+  if src:sub(1, 1) == "@" then
+    src = src:sub(2)
+  end
+  return src:match("^(.*)[/\\][^/\\]*$") or "."
+end
+package.path = this_dir() .. "/?.lua;" .. package.path
+
+local P = require("provider")
+
+local JSON_NULL = P.JSON_NULL
+
+-- Render a value for human-readable display (used for expect.value etc.).
+local function show(v)
+  if v == nil then
+    return "nil"
+  elseif v == JSON_NULL then
+    return "null"
+  elseif v == P.MISSING then
+    return "<missing>"
+  elseif type(v) == "boolean" then
+    return v and "true" or "false"
+  elseif type(v) == "string" then
+    return v
+  elseif type(v) == "number" then
+    return P.json_encode(v)
+  else
+    return P.json_encode(v)
+  end
+end
+
+local function main()
+  local prov = P.load()
+
+  local fns = prov:functions()
+  print("functions: " .. table.concat(fns, ", "))
+
+  local total = 0
+  local expect_kinds = {}
+  local input_kinds = {}
+  for _, fn in ipairs(fns) do
+    for _, entry in ipairs(prov:entries(fn)) do
+      total = total + 1
+      local ek = entry.expect.kind
+      local ik = entry.input.kind
+      expect_kinds[ek] = (expect_kinds[ek] or 0) + 1
+      input_kinds[ik] = (input_kinds[ik] or 0) + 1
+    end
+  end
+
+  print("total entries: " .. total)
+
+  -- Sort kind names for stable output.
+  local function sorted_kinds(counts)
+    local ks = {}
+    for k in pairs(counts) do
+      ks[#ks + 1] = k
+    end
+    table.sort(ks)
+    local parts = {}
+    for _, k in ipairs(ks) do
+      parts[#parts + 1] = k .. "=" .. counts[k]
+    end
+    return table.concat(parts, ", ")
+  end
+
+  print("expect kinds: " .. sorted_kinds(expect_kinds))
+  print("input kinds: " .. sorted_kinds(input_kinds))
+
+  local e = prov:entries("getpath", "basic")[1]
+  print(
+    "getpath/basic[0]: "
+      .. "id=" .. tostring(e.id)
+      .. ", doc=" .. tostring(e.doc)
+      .. ", input.kind=" .. e.input.kind
+      .. ", expect.kind=" .. e.expect.kind
+      .. ", expect.value=" .. show(e.expect.value)
+  )
+
+  -- ─── helper sanity checks ────────────────────────────────────────────────
+  print("equal(JSON_NULL, nil) lenient: " .. tostring(P.equal(JSON_NULL, nil)))
+  print(
+    "equal_strict(JSON_NULL, MISSING) vs (JSON_NULL, 1): "
+      .. tostring(P.equal_strict(JSON_NULL, P.MISSING))
+      .. " / "
+      .. tostring(P.equal_strict(JSON_NULL, 1))
+  )
+  print(
+    "error_matches substring case-insensitive: "
+      .. tostring(P.error_matches({ any = false, text = "Foo", regex = false }, "a foobar error"))
+  )
+
+  -- struct_match failure shape: build a small object {a:{b:2}} vs {a:{b:3}}.
+  local function obj(pairs_list)
+    local o = { __obj = true, keys = {}, map = {} }
+    for _, kv in ipairs(pairs_list) do
+      table.insert(o.keys, kv[1])
+      o.map[kv[1]] = kv[2]
+    end
+    return o
+  end
+  local check = obj({ { "a", obj({ { "b", 2 } }) } })
+  local base = obj({ { "a", obj({ { "b", 3 } }) } })
+  local sm = P.struct_match(check, base)
+  print(
+    "struct_match failure: ok=" .. tostring(sm.ok)
+      .. (sm.ok and "" or (", path=" .. table.concat(sm.path, ".")
+        .. ", expected=" .. show(sm.expected)
+        .. ", actual=" .. show(sm.actual)))
+  )
+end
+
+main()
diff --git a/test/proto/ocaml/provider.ml b/test/proto/ocaml/provider.ml
new file mode 100644
index 0000000..d4fdf96
--- /dev/null
+++ b/test/proto/ocaml/provider.ml
@@ -0,0 +1,592 @@
+(* Test Provider (prototype) — OCaml port of the canonical ts/provider.ts.
+ *
+ * Reads the shared corpus (build/test/test.json) and hands test code clean,
+ * normalized cases. It is NOT a test runner: it never calls the subject and
+ * never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+ *
+ * Zero runtime dependencies (OCaml stdlib only — NO yojson/findlib libs).
+ * The JSON reader is adapted from ocaml/test/runner.ml's `json_read`, producing
+ * the order-preserving `json` value type below.
+ *
+ * NOTE: This file has NOT been compiled or run — the OCaml toolchain is not
+ * available in the authoring environment. It is a faithful, self-reviewed port. *)
+
+let nullmark = "__NULL__"
+let undefmark = "__UNDEF__"
+let existsmark = "__EXISTS__"
+
+(* ---------------- json value type ---------------- *)
+
+(* Order-preserving: Obj is an association list, so functions()/groups() and
+ * struct-match leaf walks observe corpus order. *)
+type json =
+  | Null
+  | Bool of bool
+  | Num of float
+  | Str of string
+  | Arr of json list
+  | Obj of (string * json) list
+
+(* Association-list helpers (order preserving). *)
+let mem_assoc key = function
+  | Obj kvs -> List.mem_assoc key kvs
+  | _ -> false
+
+let assoc_opt key = function
+  | Obj kvs -> List.assoc_opt key kvs
+  | _ -> None
+
+(* ---------------- JSON reader -> json ----------------
+ * Adapted from ocaml/test/runner.ml's json_read; same scanning structure,
+ * retargeted to the local `json` type with order-preserving Obj. *)
+
+let json_read (s : string) : json =
+  let n = String.length s in
+  let pos = ref 0 in
+  let peek () = if !pos < n then Some s.[!pos] else None in
+  let adv () = incr pos in
+  let skip_ws () =
+    while
+      !pos < n
+      && (match s.[!pos] with ' ' | '\t' | '\n' | '\r' -> true | _ -> false)
+    do
+      incr pos
+    done
+  in
+  let rec pval () =
+    skip_ws ();
+    match peek () with
+    | Some '{' -> pobj ()
+    | Some '[' -> parr ()
+    | Some '"' -> Str (pstr ())
+    | Some 't' -> pos := !pos + 4; Bool true
+    | Some 'f' -> pos := !pos + 5; Bool false
+    | Some 'n' -> pos := !pos + 4; Null
+    | _ -> pnum ()
+  and pobj () =
+    adv (); skip_ws ();
+    if peek () = Some '}' then (adv (); Obj [])
+    else begin
+      let acc = ref [] in
+      let rec loop () =
+        skip_ws ();
+        let k = pstr () in
+        skip_ws (); adv (); (* : *)
+        let v = pval () in
+        acc := (k, v) :: !acc;
+        skip_ws ();
+        let c = (match peek () with Some c -> adv (); c | None -> '}') in
+        if c = ',' then loop () else Obj (List.rev !acc)
+      in
+      loop ()
+    end
+  and parr () =
+    adv (); skip_ws ();
+    if peek () = Some ']' then (adv (); Arr [])
+    else begin
+      let acc = ref [] in
+      let rec loop () =
+        let v = pval () in
+        acc := v :: !acc;
+        skip_ws ();
+        let c = (match peek () with Some c -> adv (); c | None -> ']') in
+        if c = ',' then loop () else Arr (List.rev !acc)
+      in
+      loop ()
+    end
+  and pstr () =
+    adv ();
+    let b = Buffer.create 16 in
+    let rec loop () =
+      let c = s.[!pos] in
+      adv ();
+      if c = '"' then Buffer.contents b
+      else if c = '\\' then begin
+        let e = s.[!pos] in
+        adv ();
+        (match e with
+         | '"' -> Buffer.add_char b '"'
+         | '\\' -> Buffer.add_char b '\\'
+         | '/' -> Buffer.add_char b '/'
+         | 'n' -> Buffer.add_char b '\n'
+         | 't' -> Buffer.add_char b '\t'
+         | 'r' -> Buffer.add_char b '\r'
+         | 'b' -> Buffer.add_char b '\b'
+         | 'f' -> Buffer.add_char b '\012'
+         | 'u' ->
+           let hex = String.sub s !pos 4 in
+           pos := !pos + 4;
+           let code = int_of_string ("0x" ^ hex) in
+           if code < 128 then Buffer.add_char b (Char.chr code)
+           else if code < 2048 then begin
+             Buffer.add_char b (Char.chr (0xC0 lor (code lsr 6)));
+             Buffer.add_char b (Char.chr (0x80 lor (code land 0x3F)))
+           end
+           else begin
+             Buffer.add_char b (Char.chr (0xE0 lor (code lsr 12)));
+             Buffer.add_char b (Char.chr (0x80 lor ((code lsr 6) land 0x3F)));
+             Buffer.add_char b (Char.chr (0x80 lor (code land 0x3F)))
+           end
+         | c -> Buffer.add_char b c);
+        loop ()
+      end
+      else (Buffer.add_char b c; loop ())
+    in
+    loop ()
+  and pnum () =
+    let start = !pos in
+    while
+      !pos < n
+      && (match s.[!pos] with
+          | '0' .. '9' | '-' | '+' | '.' | 'e' | 'E' -> true
+          | _ -> false)
+    do
+      incr pos
+    done;
+    let tok = String.sub s start (!pos - start) in
+    Num (float_of_string tok)
+  in
+  pval ()
+
+(* ---------------- normalized record types ---------------- *)
+
+type input_kind = [ `In | `Args | `Ctx ]
+type expect_kind = [ `Value | `Error | `Match | `Absent ]
+
+type input = { kind : input_kind; value : json }
+
+type error_check = { any : bool; text : string option; regex : bool }
+
+type expect = {
+  ekind : expect_kind;
+  value : json option;        (* Some _ when kind = `Value (may be Some Null) *)
+  error : error_check option;
+  match_ : json option;       (* set whenever a "match" key co-exists *)
+}
+
+type entry = {
+  function_ : string;
+  group : string;
+  index : int;
+  id : string option;
+  doc : bool;
+  client : string option;
+  input : input;
+  expect : expect;
+  raw : json;
+}
+
+(* struct_match result *)
+type match_result = {
+  ok : bool;
+  path : string list;
+  expected : json option;
+  actual : json option;
+}
+
+(* ---------------- group / function classification ---------------- *)
+
+(* A group bag is a map with a `set` array. *)
+let is_group_bag (v : json) : bool =
+  match v with
+  | Obj kvs -> (match List.assoc_opt "set" kvs with Some (Arr _) -> true | _ -> false)
+  | _ -> false
+
+(* A function node has at least one child group bag (other than "name"). *)
+let has_groups (v : json) : bool =
+  match v with
+  | Obj kvs ->
+    List.exists (fun (k, child) -> k <> "name" && is_group_bag child) kvs
+  | _ -> false
+
+(* ---------------- normalization ---------------- *)
+
+let json_to_string_opt (j : json) : string option =
+  match j with
+  | Null -> None
+  | Str s -> Some s
+  | Bool b -> Some (string_of_bool b)
+  | Num f ->
+    (* match JS String(): integral floats lose the trailing ".0" *)
+    if Float.is_integer f && Float.abs f < 1e15 then
+      Some (Printf.sprintf "%.0f" f)
+    else Some (string_of_float f)
+  | _ -> None
+
+(* raw.x present and non-null -> Some (String(x)); else None. Mirrors
+ * `null != raw.id ? String(raw.id) : null`. *)
+let str_field raw key : string option =
+  match assoc_opt key raw with
+  | None | Some Null -> None
+  | Some j -> json_to_string_opt j
+
+let resolve_input (raw : json) : input =
+  if mem_assoc "ctx" raw then
+    { kind = `Ctx; value = (match assoc_opt "ctx" raw with Some v -> v | None -> Null) }
+  else if mem_assoc "args" raw then
+    { kind = `Args; value = (match assoc_opt "args" raw with Some v -> v | None -> Null) }
+  else
+    (* kind = `In; "in" key absent => native null (Null) *)
+    { kind = `In; value = (match assoc_opt "in" raw with Some v -> v | None -> Null) }
+
+let parse_err (err : json) : error_check =
+  match err with
+  | Bool true -> { any = true; text = None; regex = false }
+  | Str s ->
+    let len = String.length s in
+    (* "/re/" — inner must be non-empty (matches /^\/(.+)\/$/) *)
+    if len >= 3 && s.[0] = '/' && s.[len - 1] = '/' then
+      { any = false; text = Some (String.sub s 1 (len - 2)); regex = true }
+    else { any = false; text = Some s; regex = false }
+  (* Non-true, non-string err spec: treat as "any error". *)
+  | _ -> { any = true; text = None; regex = false }
+
+let resolve_expect (raw : json) : expect =
+  let match_part = if mem_assoc "match" raw then assoc_opt "match" raw else None in
+  if mem_assoc "err" raw then
+    {
+      ekind = `Error;
+      value = None;
+      error = Some (parse_err (match assoc_opt "err" raw with Some v -> v | None -> Null));
+      match_ = match_part;
+    }
+  else if mem_assoc "out" raw then
+    (* KEY PRESENCE: "out" present even if Null => Value. *)
+    {
+      ekind = `Value;
+      value = Some (match assoc_opt "out" raw with Some v -> v | None -> Null);
+      error = None;
+      match_ = match_part;
+    }
+  else if mem_assoc "match" raw then
+    { ekind = `Match; value = None; error = None; match_ = match_part }
+  else { ekind = `Absent; value = None; error = None; match_ = None }
+
+let normalize fn group index (raw : json) : entry =
+  {
+    function_ = fn;
+    group;
+    index;
+    id = str_field raw "id";
+    doc = (match assoc_opt "doc" raw with Some (Bool true) -> true | _ -> false);
+    client = str_field raw "client";
+    input = resolve_input raw;
+    expect = resolve_expect raw;
+    raw;
+  }
+
+(* ---------------- TestProvider ---------------- *)
+
+(* Default corpus path: build/test/test.json relative to the repo root.
+ * This file lives at test/proto/ocaml, so up three levels reaches the root. *)
+let default_test_file () : string =
+  Filename.concat
+    (Filename.dirname (Filename.dirname (Filename.dirname (Sys.getcwd ()))))
+    (Filename.concat "build" (Filename.concat "test" "test.json"))
+
+type provider = { spec : json }
+
+(* The root holding functions: spec.struct if present, else spec itself. *)
+let root_of (spec : json) : json =
+  match assoc_opt "struct" spec with Some r -> r | None -> spec
+
+let load ?path () : provider =
+  let file =
+    match path with
+    | Some p -> p
+    | None ->
+      (* Prefer the conventional path relative to cwd if it exists, else the
+       * repo-root-relative default. *)
+      let cand = Filename.concat "build" (Filename.concat "test" "test.json") in
+      if Sys.file_exists cand then cand
+      else
+        let d = default_test_file () in
+        if Sys.file_exists d then d else cand
+  in
+  let ic = open_in_bin file in
+  let len = in_channel_length ic in
+  let raw = really_input_string ic len in
+  close_in ic;
+  { spec = json_read raw }
+
+let raw (p : provider) : json = p.spec
+
+let fn_node (p : provider) (fn : string) : json =
+  let node =
+    match assoc_opt fn (root_of p.spec) with
+    | Some n -> Some n
+    | None -> assoc_opt fn p.spec
+  in
+  match node with
+  | Some n -> n
+  | None -> failwith (Printf.sprintf "Unknown function: %s" fn)
+
+let functions (p : provider) : string list =
+  match root_of p.spec with
+  | Obj kvs ->
+    List.filter_map
+      (fun (k, v) -> if is_group_bag v || has_groups v then Some k else None)
+      kvs
+  | _ -> []
+
+let groups (p : provider) (fn : string) : string list =
+  match fn_node p fn with
+  | Obj kvs ->
+    List.filter_map
+      (fun (k, v) -> if k <> "name" && is_group_bag v then Some k else None)
+      kvs
+  | _ -> []
+
+let entries ?group (p : provider) (fn : string) : entry list =
+  let node = fn_node p fn in
+  let gs = match group with Some g -> [ g ] | None -> groups p fn in
+  let per_group g =
+    match assoc_opt g node with
+    | Some bag when is_group_bag bag -> (
+        match assoc_opt "set" bag with
+        | Some (Arr items) -> List.mapi (fun i it -> normalize fn g i it) items
+        | _ -> [])
+    | _ -> []
+  in
+  List.concat (List.map per_group gs)
+
+(* ---------------- pure comparison helpers ---------------- *)
+
+(* Compact JSON serialization (used by stringify for non-string values). *)
+let rec json_compact (j : json) : string =
+  match j with
+  | Null -> "null"
+  | Bool b -> string_of_bool b
+  | Num f ->
+    if Float.is_integer f && Float.abs f < 1e15 then Printf.sprintf "%.0f" f
+    else
+      (* JSON has no trailing-dot integers; OCaml's string_of_float gives "1."
+       * for 1.0 but that branch is handled above. *)
+      let s = Printf.sprintf "%.17g" f in
+      s
+  | Str s -> json_quote s
+  | Arr xs -> "[" ^ String.concat "," (List.map json_compact xs) ^ "]"
+  | Obj kvs ->
+    "{"
+    ^ String.concat ","
+        (List.map (fun (k, v) -> json_quote k ^ ":" ^ json_compact v) kvs)
+    ^ "}"
+
+and json_quote (s : string) : string =
+  let b = Buffer.create (String.length s + 2) in
+  Buffer.add_char b '"';
+  String.iter
+    (fun c ->
+      match c with
+      | '"' -> Buffer.add_string b "\\\""
+      | '\\' -> Buffer.add_string b "\\\\"
+      | '\n' -> Buffer.add_string b "\\n"
+      | '\t' -> Buffer.add_string b "\\t"
+      | '\r' -> Buffer.add_string b "\\r"
+      | '\b' -> Buffer.add_string b "\\b"
+      | '\012' -> Buffer.add_string b "\\f"
+      | c when Char.code c < 0x20 ->
+        Buffer.add_string b (Printf.sprintf "\\u%04x" (Char.code c))
+      | c -> Buffer.add_char b c)
+    s;
+  Buffer.add_char b '"';
+  Buffer.contents b
+
+(* stringify(x) = x if it is already a string, else compact JSON. *)
+let stringify (x : json) : string =
+  match x with Str s -> s | _ -> json_compact x
+
+(* normNull: __NULL__ and absent collapse to Null (recursive). The provider's
+ * json has no "absent" leaf, so only Str __NULL__ collapses here. *)
+let rec norm_null (x : json) : json =
+  match x with
+  | Str s when s = nullmark -> Null
+  | Arr xs -> Arr (List.map norm_null xs)
+  | Obj kvs -> Obj (List.map (fun (k, v) -> (k, norm_null v)) kvs)
+  | _ -> x
+
+(* normMark: only __NULL__ -> Null (strict variant). *)
+let rec norm_mark (x : json) : json =
+  match x with
+  | Str s when s = nullmark -> Null
+  | Arr xs -> Arr (List.map norm_mark xs)
+  | Obj kvs -> Obj (List.map (fun (k, v) -> (k, norm_mark v)) kvs)
+  | _ -> x
+
+(* Case-insensitive substring containment. *)
+let contains_ci (hay : string) (needle : string) : bool =
+  let low = String.lowercase_ascii in
+  let hay = low hay and needle = low needle in
+  let hl = String.length hay and nl = String.length needle in
+  if nl = 0 then true
+  else
+    let rec go i =
+      if i + nl > hl then false
+      else if String.sub hay i nl = needle then true
+      else go (i + 1)
+    in
+    go 0
+
+(* Plain (case-sensitive) substring search — used by the simplified regex
+ * fallback. *)
+let contains_cs (hay : string) (needle : string) : bool =
+  let hl = String.length hay and nl = String.length needle in
+  if nl = 0 then true
+  else
+    let rec go i =
+      if i + nl > hl then false
+      else if String.sub hay i nl = needle then true
+      else go (i + 1)
+    in
+    go 0
+
+(* PROTOTYPE: regex simplified.
+ * The canonical TS uses JS RegExp(text).test(str). To stay fully
+ * dependency-free (no Str module / findlib lib), we approximate: an unanchored
+ * pattern with no regex metacharacters is treated as a plain substring test;
+ * anchors (^ / $) are honored against the trimmed literal. Patterns using other
+ * metacharacters fall back to a literal substring test of the metachar-stripped
+ * pattern. This is sufficient for the corpus's simple error/regex cases but is
+ * NOT a full regex engine. *)
+let regex_test (pat : string) (str : string) : bool =
+  let plen = String.length pat in
+  let anchored_start = plen > 0 && pat.[0] = '^' in
+  let anchored_end = plen > 0 && pat.[plen - 1] = '$' in
+  let core =
+    let lo = if anchored_start then 1 else 0 in
+    let hi = if anchored_end then plen - 1 else plen in
+    if hi >= lo then String.sub pat lo (hi - lo) else ""
+  in
+  (* Strip simple metacharacters for the literal fallback. *)
+  let is_meta = function
+    | '.' | '*' | '+' | '?' | '(' | ')' | '[' | ']' | '{' | '}' | '|' | '\\' ->
+      true
+    | _ -> false
+  in
+  let str_exists pred s =
+    let len = String.length s in
+    let rec go i = i < len && (pred s.[i] || go (i + 1)) in
+    go 0
+  in
+  let literal = String.length core > 0 && not (str_exists is_meta core) in
+  if literal then
+    if anchored_start && anchored_end then String.equal str core
+    else if anchored_start then
+      String.length str >= String.length core
+      && String.sub str 0 (String.length core) = core
+    else if anchored_end then
+      let sl = String.length str and cl = String.length core in
+      sl >= cl && String.sub str (sl - cl) cl = core
+    else contains_cs str core
+  else
+    (* Metacharacter fallback: substring of the metachar-free remainder. *)
+    let buf = Buffer.create (String.length core) in
+    String.iter (fun c -> if not (is_meta c) then Buffer.add_char buf c) core;
+    let stripped = Buffer.contents buf in
+    if String.length stripped = 0 then true else contains_cs str stripped
+
+(* Deep structural equality. Obj compared order-independently (key set + per-key
+ * deep eq), Arr positionally. Mirrors deepEq in the canonical port; Bool/Num
+ * never conflate (distinct json constructors). *)
+let rec deep_eq (a : json) (b : json) : bool =
+  match (a, b) with
+  | Null, Null -> true
+  | Bool x, Bool y -> x = y
+  | Num x, Num y -> x = y
+  | Str x, Str y -> String.equal x y
+  | Arr xs, Arr ys ->
+    List.length xs = List.length ys && List.for_all2 deep_eq xs ys
+  | Obj xs, Obj ys ->
+    List.length xs = List.length ys
+    && List.for_all
+         (fun (k, v) -> match List.assoc_opt k ys with Some w -> deep_eq v w | None -> false)
+         xs
+  | _ -> false
+
+(* matchval(check, base): check === base; else string handling; else false.
+ * (A function check would be `true`, but json has no function leaf.) *)
+let matchval (check : json) (base : json) : bool =
+  if deep_eq check base then true
+  else
+    match check with
+    | Str cs ->
+      let basestr = stringify base in
+      let len = String.length cs in
+      if len >= 3 && cs.[0] = '/' && cs.[len - 1] = '/' then
+        regex_test (String.sub cs 1 (len - 2)) basestr
+      else contains_ci basestr cs
+    | _ -> false
+
+let equal (expected : json) (actual : json) : bool =
+  deep_eq (norm_null expected) (norm_null actual)
+
+(* Strict variant for the runner's `{ null: false }` functions: only __NULL__
+ * is normalized, native Null stays distinct. *)
+let equal_strict (expected : json) (actual : json) : bool =
+  deep_eq (norm_mark expected) (norm_mark actual)
+
+let error_matches (check : error_check) (message : string) : bool =
+  if check.any then true
+  else
+    match check.text with
+    | None -> false
+    | Some text -> if check.regex then regex_test text message else contains_ci message text
+
+(* getpath over json. Returns None for an absent key/out-of-range index (the
+ * provider's analogue of `undefined`); a present Null returns Some Null. *)
+let getpath (store : json) (path : string list) : json option =
+  let rec go cur = function
+    | [] -> Some cur
+    | key :: rest -> (
+        match cur with
+        | Obj kvs -> (match List.assoc_opt key kvs with Some v -> go v rest | None -> None)
+        | Arr xs -> (
+            match int_of_string_opt key with
+            | Some i when i >= 0 && i < List.length xs -> go (List.nth xs i) rest
+            | _ -> None)
+        | Null -> None
+        | _ -> None)
+  in
+  go store path
+
+let is_node (v : json) : bool = match v with Obj _ | Arr _ -> true | _ -> false
+
+(* Walk every leaf of `node`, invoking fn with (leaf, path). Object keys walked
+ * in corpus (assoc-list) order; array indices as stringified positions. *)
+let walk_leaves (node : json) (fn : json -> string list -> unit) : unit =
+  let rec go node path =
+    match node with
+    | Arr xs -> List.iteri (fun i v -> go v (path @ [ string_of_int i ])) xs
+    | Obj kvs -> List.iter (fun (k, v) -> go v (path @ [ k ])) kvs
+    | _ -> fn node path
+  in
+  go node []
+
+(* Partial structural match: every leaf of `check` must match `base` at its
+ * path. First failure returns its path + the two values. *)
+let struct_match (check : json) (base : json) : match_result =
+  let result = ref { ok = true; path = []; expected = None; actual = None } in
+  walk_leaves check (fun v path ->
+      if (!result).ok then begin
+        let baseval = getpath base path in
+        let direct =
+          match baseval with Some bv -> deep_eq bv v | None -> false
+        in
+        if direct then ()
+        else if v = Str undefmark && baseval = None then ()
+        else if
+          v = Str existsmark
+          && (match baseval with Some Null | None -> false | Some _ -> true)
+        then ()
+        else
+          let compare_base = match baseval with Some bv -> bv | None -> Null in
+          if not (matchval v compare_base) then
+            result :=
+              {
+                ok = false;
+                path;
+                expected = Some v;
+                actual = baseval;
+              }
+      end);
+  !result
diff --git a/test/proto/ocaml/smoke.ml b/test/proto/ocaml/smoke.ml
new file mode 100644
index 0000000..06d17cc
--- /dev/null
+++ b/test/proto/ocaml/smoke.ml
@@ -0,0 +1,84 @@
+(* Smoke test for the OCaml test provider port. Prints summary stats that must
+ * match the canonical TS output documented in PROVIDER work.
+ *
+ * NOTE: NOT compiled/run — the OCaml toolchain is unavailable in the authoring
+ * environment. Self-reviewed against the canonical ts/provider.ts. *)
+
+open Provider
+
+(* Render an expect_kind / input_kind as its canonical lowercase tag. *)
+let expect_kind_str = function
+  | `Value -> "value"
+  | `Error -> "error"
+  | `Match -> "match"
+  | `Absent -> "absent"
+
+let input_kind_str = function `In -> "in" | `Args -> "args" | `Ctx -> "ctx"
+
+(* Count occurrences, preserving a fixed display order. *)
+let count_in_order order tbl =
+  List.filter_map
+    (fun k -> match List.assoc_opt k tbl with Some c when c > 0 -> Some (k, c) | _ -> None)
+    order
+
+let bump tbl k =
+  let cur = match List.assoc_opt k !tbl with Some c -> c | None -> 0 in
+  tbl := (k, cur + 1) :: List.remove_assoc k !tbl
+
+let () =
+  let prov = load () in
+
+  let fns = functions prov in
+  Printf.printf "functions: %s\n" (String.concat ", " fns);
+
+  let total = ref 0 in
+  let expect_kinds = ref [] in
+  let input_kinds = ref [] in
+  List.iter
+    (fun fn ->
+      List.iter
+        (fun e ->
+          incr total;
+          bump expect_kinds (expect_kind_str e.expect.ekind);
+          bump input_kinds (input_kind_str e.input.kind))
+        (entries prov fn))
+    fns;
+
+  Printf.printf "total entries: %d\n" !total;
+
+  (* Fixed order to match the documented expected line. *)
+  let ek = count_in_order [ "value"; "absent"; "match"; "error" ] !expect_kinds in
+  Printf.printf "expect kinds: %s\n"
+    (String.concat ", " (List.map (fun (k, c) -> Printf.sprintf "%s=%d" k c) ek));
+
+  let ik = count_in_order [ "in"; "args"; "ctx" ] !input_kinds in
+  Printf.printf "input kinds: %s\n"
+    (String.concat ", " (List.map (fun (k, c) -> Printf.sprintf "%s=%d" k c) ik));
+
+  let e = List.hd (entries ~group:"basic" prov "getpath") in
+  let id_str = match e.id with Some s -> s | None -> "null" in
+  let value_str =
+    match e.expect.value with Some v -> stringify v | None -> "null"
+  in
+  Printf.printf
+    "getpath/basic[0]: id=%s, doc=%b, input.kind=%s, expect.kind=%s, expect.value=%s\n"
+    id_str e.doc
+    (input_kind_str e.input.kind)
+    (expect_kind_str e.expect.ekind)
+    value_str;
+
+  (* ---- helper sanity checks ---- *)
+  Printf.printf "equal(Null, Null) lenient: %b\n" (equal Null Null);
+  Printf.printf "equal_strict(Null, __NULL__): %b / equal_strict(Null, 1): %b\n"
+    (equal_strict Null (Str nullmark))
+    (equal_strict Null (Num 1.0));
+  Printf.printf "error_matches substring ci: %b\n"
+    (error_matches { any = false; text = Some "Foo"; regex = false } "a foobar error");
+  let sm =
+    struct_match (Obj [ ("a", Obj [ ("b", Num 2.0) ]) ]) (Obj [ ("a", Obj [ ("b", Num 3.0) ]) ])
+  in
+  Printf.printf "struct_match failure: {ok=%b, path=%s, expected=%s, actual=%s}\n"
+    sm.ok
+    (String.concat "/" sm.path)
+    (match sm.expected with Some v -> stringify v | None -> "")
+    (match sm.actual with Some v -> stringify v | None -> "")
diff --git a/test/proto/perl/Provider.pm b/test/proto/perl/Provider.pm
new file mode 100644
index 0000000..ea47ed6
--- /dev/null
+++ b/test/proto/perl/Provider.pm
@@ -0,0 +1,533 @@
+# Test Provider (prototype) — Perl port of the canonical ts/provider.ts.
+#
+# Reads the shared corpus (build/test/test.json) and hands test code clean,
+# normalized cases. It is NOT a test runner: it never calls the subject and
+# never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+#
+# Zero runtime dependencies: CORE modules only. JSON booleans use JSON::PP
+# (a core module). Perl hashes are unordered, so to preserve the corpus key
+# order for functions()/groups() we parse the JSON with a tiny pure-Perl
+# recursive-descent reader that records first-seen key order into an inline
+# insertion-ordered tied hash (OrderedHash, below). Values (numbers, strings,
+# booleans, null, nested maps/lists) decode to the same shapes JSON::PP would
+# yield: JSON::PP::Boolean for true/false, undef for null.
+
+package Voxgig::Struct::Proto;
+
+use strict;
+use warnings;
+use Exporter 'import';
+use File::Spec;
+use File::Basename qw(dirname);
+use JSON::PP ();
+
+our @EXPORT_OK = qw(
+    matchval equal equal_strict struct_match error_matches stringify
+);
+
+my $NULLMARK   = '__NULL__';
+my $UNDEFMARK  = '__UNDEF__';
+my $EXISTSMARK = '__EXISTS__';
+
+# ─── inline insertion-ordered hash ──────────────────────────────────────────
+# A minimal tied hash that remembers key insertion order. It behaves as an
+# ordained hashref for all normal access; ->ordered_keys gives corpus order.
+
+{
+    package Voxgig::Struct::Proto::OrderedHash;
+
+    sub TIEHASH {
+        my ($class) = @_;
+        return bless { keys => [], data => {} }, $class;
+    }
+    sub STORE {
+        my ($self, $k, $v) = @_;
+        push @{ $self->{keys} }, $k unless exists $self->{data}{$k};
+        $self->{data}{$k} = $v;
+    }
+    sub FETCH    { $_[0]->{data}{ $_[1] } }
+    sub EXISTS   { exists $_[0]->{data}{ $_[1] } }
+    sub DELETE   {
+        my ($self, $k) = @_;
+        @{ $self->{keys} } = grep { $_ ne $k } @{ $self->{keys} };
+        delete $self->{data}{$k};
+    }
+    sub CLEAR    { $_[0]->{keys} = []; $_[0]->{data} = {} }
+    sub FIRSTKEY { $_[0]->{iter} = 0; $_[0]->{keys}[0] }
+    sub NEXTKEY  {
+        my ($self) = @_;
+        return $self->{keys}[ ++$self->{iter} ];
+    }
+    sub SCALAR   { scalar %{ $_[0]->{data} } }
+}
+
+# Make a fresh ordered hashref.
+sub _ordered_hash {
+    my %h;
+    tie %h, 'Voxgig::Struct::Proto::OrderedHash';
+    return \%h;
+}
+
+# Ordered keys of a (possibly ordered) hashref. Falls back to plain keys.
+sub _okeys {
+    my ($h) = @_;
+    my $t = tied %$h;
+    return @{ $t->{keys} } if $t;
+    return keys %$h;
+}
+
+# ─── tiny order-preserving JSON reader ──────────────────────────────────────
+# Recursive descent over the raw text. Numbers/strings/null/true/false decode
+# to plain Perl scalars / undef / JSON::PP::Boolean. Objects become ordered.
+
+sub _parse_json {
+    my ($text) = @_;
+    my $pos = 0;
+    my $val = _p_value($text, \$pos);
+    _p_ws($text, \$pos);
+    die "Trailing content in JSON at offset $pos\n" if $pos < length $text;
+    return $val;
+}
+
+sub _p_ws {
+    my ($t, $p) = @_;
+    pos($t) = $$p;
+    $t =~ /\G[\x20\x09\x0A\x0D]*/gc;
+    $$p = pos($t);
+}
+
+sub _p_value {
+    my ($t, $p) = @_;
+    _p_ws($t, $p);
+    my $c = substr($t, $$p, 1);
+    return _p_object($t, $p) if $c eq '{';
+    return _p_array($t, $p)  if $c eq '[';
+    return _p_string($t, $p) if $c eq '"';
+    if ($c eq 't') { $$p += 4; return JSON::PP::true }
+    if ($c eq 'f') { $$p += 5; return JSON::PP::false }
+    if ($c eq 'n') { $$p += 4; return undef }
+    return _p_number($t, $p);
+}
+
+sub _p_object {
+    my ($t, $p) = @_;
+    my $obj = _ordered_hash();
+    $$p++;    # consume {
+    _p_ws($t, $p);
+    if (substr($t, $$p, 1) eq '}') { $$p++; return $obj }
+    while (1) {
+        _p_ws($t, $p);
+        my $key = _p_string($t, $p);
+        _p_ws($t, $p);
+        $$p++;    # consume :
+        my $v = _p_value($t, $p);
+        $obj->{$key} = $v;
+        _p_ws($t, $p);
+        my $c = substr($t, $$p, 1);
+        $$p++;
+        last if $c eq '}';
+        # else c eq ',' → continue
+    }
+    return $obj;
+}
+
+sub _p_array {
+    my ($t, $p) = @_;
+    my @arr;
+    $$p++;    # consume [
+    _p_ws($t, $p);
+    if (substr($t, $$p, 1) eq ']') { $$p++; return \@arr }
+    while (1) {
+        my $v = _p_value($t, $p);
+        push @arr, $v;
+        _p_ws($t, $p);
+        my $c = substr($t, $$p, 1);
+        $$p++;
+        last if $c eq ']';
+        # else ',' → continue
+    }
+    return \@arr;
+}
+
+my %ESC = (
+    '"' => '"', '\\' => '\\', '/' => '/',
+    'b' => "\b", 'f' => "\f", 'n' => "\n", 'r' => "\r", 't' => "\t",
+);
+
+sub _p_string {
+    my ($t, $p) = @_;
+    $$p++;    # consume opening "
+    my $out = '';
+    while (1) {
+        my $c = substr($t, $$p, 1);
+        if ($c eq '"') { $$p++; last }
+        if ($c eq '\\') {
+            my $e = substr($t, $$p + 1, 1);
+            if ($e eq 'u') {
+                my $hex = substr($t, $$p + 2, 4);
+                $out .= chr(hex($hex));
+                $$p += 6;
+            }
+            else {
+                $out .= $ESC{$e} // $e;
+                $$p += 2;
+            }
+        }
+        else {
+            $out .= $c;
+            $$p++;
+        }
+    }
+    return $out;
+}
+
+sub _p_number {
+    my ($t, $p) = @_;
+    pos($t) = $$p;
+    $t =~ /\G(-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][-+]?[0-9]+)?)/gc;
+    my $num = $1;
+    $$p = pos($t);
+    return $num + 0;
+}
+
+# ─── default corpus path ────────────────────────────────────────────────────
+# build/test/test.json relative to this module file (test/proto/perl).
+
+sub _default_testfile {
+    my $here = dirname(__FILE__);    # test/proto/perl
+    return File::Spec->catfile($here, '..', '..', '..', 'build', 'test', 'test.json');
+}
+
+# ─── provider ───────────────────────────────────────────────────────────────
+
+sub load {
+    my ($class, $testfile) = @_;
+    # Allow both Voxgig::Struct::Proto->load(...) and load(...) call styles.
+    unless (defined $class && $class eq __PACKAGE__) {
+        $testfile = $class;
+        $class    = __PACKAGE__;
+    }
+    $testfile = _default_testfile() unless defined $testfile;
+    open my $fh, '<:raw', $testfile or die "Cannot open $testfile: $!\n";
+    local $/;
+    my $text = <$fh>;
+    close $fh;
+    my $spec = _parse_json($text);
+    return bless { spec => $spec }, $class;
+}
+
+sub raw {
+    my ($self) = @_;
+    return $self->{spec};
+}
+
+# A group bag is a map with a `set` array.
+sub _is_group_bag {
+    my ($v) = @_;
+    return 0 unless _is_map($v);
+    my $set = $v->{set};
+    return ($set && ref($set) eq 'ARRAY') ? 1 : 0;
+}
+
+# A function node has at least one child group bag (excluding `name`).
+sub _has_groups {
+    my ($v) = @_;
+    return 0 unless _is_map($v);
+    for my $k (_okeys($v)) {
+        next if $k eq 'name';
+        return 1 if _is_group_bag($v->{$k});
+    }
+    return 0;
+}
+
+sub _fn_node {
+    my ($self, $fn) = @_;
+    my $spec = $self->{spec};
+    my $node;
+    if (_is_map($spec->{struct}) && exists $spec->{struct}{$fn}) {
+        $node = $spec->{struct}{$fn};
+    }
+    elsif (exists $spec->{$fn}) {
+        $node = $spec->{$fn};
+    }
+    die "Unknown function: $fn\n" unless defined $node;
+    return $node;
+}
+
+sub functions {
+    my ($self) = @_;
+    my $spec = $self->{spec};
+    my $root = (_is_map($spec->{struct})) ? $spec->{struct} : $spec;
+    return [ grep { _is_group_bag($root->{$_}) || _has_groups($root->{$_}) } _okeys($root) ];
+}
+
+sub groups {
+    my ($self, $fn) = @_;
+    my $node = $self->_fn_node($fn);
+    return [ grep { $_ ne 'name' && _is_group_bag($node->{$_}) } _okeys($node) ];
+}
+
+sub entries {
+    my ($self, $fn, $group) = @_;
+    my $node = $self->_fn_node($fn);
+    my @groups = defined $group ? ($group) : @{ $self->groups($fn) };
+    my @out;
+    for my $g (@groups) {
+        my $bag = $node->{$g};
+        next unless _is_group_bag($bag);
+        my $set = $bag->{set};
+        for (my $i = 0; $i < @$set; $i++) {
+            push @out, _normalize($fn, $g, $i, $set->[$i]);
+        }
+    }
+    return \@out;
+}
+
+# ─── value-shape helpers ────────────────────────────────────────────────────
+
+sub _is_map  { defined $_[0] && ref($_[0]) eq 'HASH' }
+sub _is_list { defined $_[0] && ref($_[0]) eq 'ARRAY' }
+
+sub _is_jbool { ref($_[0]) eq 'JSON::PP::Boolean' }
+sub _jtrue    { _is_jbool($_[0]) && $_[0] }    # JSON::PP::Boolean overloads bool
+
+# ─── normalization ──────────────────────────────────────────────────────────
+
+sub _normalize {
+    my ($fn, $group, $index, $raw) = @_;
+    my $h = {
+        function => $fn,
+        group    => $group,
+        index    => $index,
+        id       => (exists $raw->{id} && defined $raw->{id}) ? "$raw->{id}" : undef,
+        doc      => (exists $raw->{doc} && _jtrue($raw->{doc})) ? 1 : 0,
+        client   => (exists $raw->{client} && defined $raw->{client}) ? "$raw->{client}" : undef,
+        input    => _resolve_input($raw),
+        expect   => _resolve_expect($raw),
+        raw      => $raw,
+    };
+    return $h;
+}
+
+sub _resolve_input {
+    my ($raw) = @_;
+    if (exists $raw->{ctx}) {
+        return { kind => 'ctx', ctx => $raw->{ctx} };
+    }
+    if (exists $raw->{args}) {
+        return { kind => 'args', args => $raw->{args} };
+    }
+    return { kind => 'in', in => (exists $raw->{in} ? $raw->{in} : undef) };
+}
+
+sub _parse_err {
+    my ($err) = @_;
+    if (_is_jbool($err) && $err) {
+        return { any => 1, text => undef, regex => 0 };
+    }
+    if (!ref $err && defined $err) {
+        if ($err =~ m{^/(.+)/$}s) {
+            return { any => 0, text => $1, regex => 1 };
+        }
+        return { any => 0, text => $err, regex => 0 };
+    }
+    # Non-true, non-string err spec: treat as "any error".
+    return { any => 1, text => undef, regex => 0 };
+}
+
+sub _resolve_expect {
+    my ($raw) = @_;
+    my $has_match = exists $raw->{match};
+    my $match_part = $has_match ? $raw->{match} : undef;
+    if (exists $raw->{err}) {
+        return { kind => 'error', error => _parse_err($raw->{err}), match => $match_part };
+    }
+    if (exists $raw->{out}) {
+        return { kind => 'value', value => $raw->{out}, match => $match_part };
+    }
+    if ($has_match) {
+        return { kind => 'match', match => $raw->{match} };
+    }
+    return { kind => 'absent' };
+}
+
+# ─── pure comparison helpers ────────────────────────────────────────────────
+
+# stringify(x) = x if already a (plain) string, else compact JSON.
+# In Perl, scalars are stringy/numbery; we treat any non-ref defined scalar
+# (that is not a JSON::PP::Boolean) as "already a string" and pass it through.
+# Refs, undef, and booleans get compact-JSON encoded (allow_nonref handles
+# bare scalars/undef should they reach the encoder).
+sub stringify {
+    my ($x) = @_;
+    return $x if (defined $x && !ref $x);
+    return JSON::PP->new->canonical(0)->allow_nonref->encode($x);
+}
+
+sub _norm_null {
+    my ($x) = @_;
+    return undef if (!defined $x);
+    return undef if (!ref $x && $x eq $NULLMARK);
+    if (_is_list($x)) {
+        return [ map { _norm_null($_) } @$x ];
+    }
+    if (_is_map($x)) {
+        my %o;
+        for my $k (_okeys($x)) { $o{$k} = _norm_null($x->{$k}) }
+        return \%o;
+    }
+    return $x;
+}
+
+sub _norm_mark {
+    my ($x) = @_;
+    return undef if (defined $x && !ref $x && $x eq $NULLMARK);
+    if (_is_list($x)) {
+        return [ map { _norm_mark($_) } @$x ];
+    }
+    if (_is_map($x)) {
+        my %o;
+        for my $k (_okeys($x)) { $o{$k} = _norm_mark($x->{$k}) }
+        return \%o;
+    }
+    return $x;
+}
+
+sub matchval {
+    my ($check, $base) = @_;
+    return 1 if _scalar_eq($check, $base);
+    if (defined $check && !ref $check) {
+        my $basestr = stringify($base);
+        if ($check =~ m{^/(.+)/$}s) {
+            my $re = $1;
+            return ($basestr =~ /$re/) ? 1 : 0;
+        }
+        return (index(lc $basestr, lc $check) >= 0) ? 1 : 0;
+    }
+    if (ref $check eq 'CODE') {
+        return 1;
+    }
+    return 0;
+}
+
+# Scalar-level identity for matchval's `check === base` first branch.
+sub _scalar_eq {
+    my ($a, $b) = @_;
+    my $an = !defined $a;
+    my $bn = !defined $b;
+    return 1 if $an && $bn;
+    return 0 if $an || $bn;
+    return 0 if ref $a || ref $b;
+    # Numeric-ish vs string compare: use string eq (JSON scalars compare fine).
+    return ($a eq $b) ? 1 : 0;
+}
+
+sub equal {
+    my ($expected, $actual) = @_;
+    return _deep_eq(_norm_null($expected), _norm_null($actual));
+}
+
+sub equal_strict {
+    my ($expected, $actual) = @_;
+    return _deep_eq(_norm_mark($expected), _norm_mark($actual));
+}
+
+sub _deep_eq {
+    my ($a, $b) = @_;
+    my $an = !defined $a;
+    my $bn = !defined $b;
+    return 1 if $an && $bn;
+    return 0 if $an || $bn;
+    if (_is_list($a) && _is_list($b)) {
+        return 0 unless @$a == @$b;
+        for (my $i = 0; $i < @$a; $i++) {
+            return 0 unless _deep_eq($a->[$i], $b->[$i]);
+        }
+        return 1;
+    }
+    if (_is_map($a) && _is_map($b)) {
+        my @ak = keys %$a;
+        my @bk = keys %$b;
+        return 0 unless @ak == @bk;
+        for my $k (@ak) {
+            return 0 unless exists $b->{$k};
+            return 0 unless _deep_eq($a->{$k}, $b->{$k});
+        }
+        return 1;
+    }
+    return 0 if ref $a || ref $b;
+    # Two non-ref scalars: compare via string (handles numbers and strings).
+    return ($a eq $b) ? 1 : 0;
+}
+
+sub error_matches {
+    my ($check, $message) = @_;
+    return 1 if $check->{any};
+    return 0 if !defined $check->{text};
+    if ($check->{regex}) {
+        my $re = $check->{text};
+        return ($message =~ /$re/) ? 1 : 0;
+    }
+    return (index(lc $message, lc $check->{text}) >= 0) ? 1 : 0;
+}
+
+# Partial structural match: every leaf of `check` must match `base` at its path.
+sub struct_match {
+    my ($check, $base) = @_;
+    my $result = { ok => 1 };
+    _walk_leaves($check, [], sub {
+        my ($val, $path) = @_;
+        return unless $result->{ok};
+        my $baseval = _getpath($base, $path);
+        return if _scalar_eq($val, $baseval);
+        if (defined $val && !ref $val && $val eq $UNDEFMARK && !defined $baseval) {
+            return;
+        }
+        if (defined $val && !ref $val && $val eq $EXISTSMARK && defined $baseval) {
+            return;
+        }
+        if (!matchval($val, $baseval)) {
+            $result = { ok => 0, path => $path, expected => $val, actual => $baseval };
+        }
+    });
+    return $result;
+}
+
+sub _is_node { _is_map($_[0]) || _is_list($_[0]) }
+
+sub _walk_leaves {
+    my ($node, $path, $fn) = @_;
+    if (_is_list($node)) {
+        for (my $i = 0; $i < @$node; $i++) {
+            _walk_leaves($node->[$i], [ @$path, "$i" ], $fn);
+        }
+    }
+    elsif (_is_map($node)) {
+        for my $k (_okeys($node)) {
+            _walk_leaves($node->{$k}, [ @$path, $k ], $fn);
+        }
+    }
+    else {
+        $fn->($node, $path);
+    }
+}
+
+sub _getpath {
+    my ($store, $path) = @_;
+    my $cur = $store;
+    for my $key (@$path) {
+        return undef unless defined $cur;
+        if (_is_list($cur)) {
+            $cur = $cur->[ $key + 0 ];
+        }
+        elsif (_is_map($cur)) {
+            $cur = $cur->{$key};
+        }
+        else {
+            return undef;
+        }
+    }
+    return $cur;
+}
+
+1;
diff --git a/test/proto/perl/smoke.pl b/test/proto/perl/smoke.pl
new file mode 100644
index 0000000..6c270d0
--- /dev/null
+++ b/test/proto/perl/smoke.pl
@@ -0,0 +1,65 @@
+#!/usr/bin/env perl
+# Smoke test for the Perl test provider port. Prints summary stats that must
+# match the canonical TS output documented in PROVIDER.md.
+
+use strict;
+use warnings;
+use FindBin;
+use lib $FindBin::Bin;
+require "$FindBin::Bin/Provider.pm";
+Voxgig::Struct::Proto->import(qw(equal equal_strict error_matches struct_match));
+
+sub main {
+    my $prov = Voxgig::Struct::Proto->load;
+
+    my $fns = $prov->functions;
+    print 'functions: ', join(', ', @$fns), "\n";
+
+    my $total = 0;
+    my %expect_kinds;
+    my %input_kinds;
+    for my $fn (@$fns) {
+        for my $entry (@{ $prov->entries($fn) }) {
+            $total++;
+            $expect_kinds{ $entry->{expect}{kind} }++;
+            $input_kinds{ $entry->{input}{kind} }++;
+        }
+    }
+
+    print "total entries: $total\n";
+
+    # Fixed order to match the documented expected line.
+    my @ek_order = qw(value absent match error);
+    print 'expect kinds: ',
+        join(', ', map { "$_=" . ($expect_kinds{$_} // 0) } @ek_order), "\n";
+
+    my @ik_order = qw(in args ctx);
+    print 'input kinds: ',
+        join(', ', map { "$_=$input_kinds{$_}" } grep { $input_kinds{$_} } @ik_order),
+        "\n";
+
+    my $e = $prov->entries('getpath', 'basic')->[0];
+    my $doc = $e->{doc} ? 'true(=1)' : 'false(=0)';
+    printf
+        "getpath/basic[0]: id=%s, doc=%s, input.kind=%s, expect.kind=%s, expect.value=%s\n",
+        $e->{id}, $doc, $e->{input}{kind}, $e->{expect}{kind}, $e->{expect}{value};
+
+    # ─── helper sanity checks ──────────────────────────────────────────────
+    print 'equal(undef, missing) lenient: ', (equal(undef, undef) ? 'true' : 'false'), "\n";
+    print 'equal_strict(undef, __NULL__): ',
+        (equal_strict(undef, '__NULL__') ? 'true' : 'false'),
+        ' / equal_strict(undef, 1): ',
+        (equal_strict(undef, 1) ? 'true' : 'false'), "\n";
+    print 'error_matches substring ci: ',
+        (error_matches({ any => 0, text => 'Foo', regex => 0 }, 'a foobar error') ? 'true' : 'false'),
+        "\n";
+    my $sm = struct_match({ a => { b => 2 } }, { a => { b => 3 } });
+    print 'struct_match failure: ',
+        sprintf('{ok=%s, path=%s, expected=%s, actual=%s}',
+            $sm->{ok} ? 1 : 0,
+            join('/', @{ $sm->{path} // [] }),
+            $sm->{expected} // '', $sm->{actual} // ''),
+        "\n";
+}
+
+main();
diff --git a/test/proto/php/provider.php b/test/proto/php/provider.php
new file mode 100644
index 0000000..7e5fc42
--- /dev/null
+++ b/test/proto/php/provider.php
@@ -0,0 +1,493 @@
+<?php
+
+// Test Provider (prototype) — PHP port of the canonical ts/provider.ts.
+//
+// Reads the shared corpus (build/test/test.json) and hands test code clean,
+// normalized cases. It is NOT a test runner: it never calls the subject and
+// never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+//
+// Zero runtime dependencies (stdlib only), matching repo policy.
+
+declare(strict_types=1);
+
+namespace Voxgig\Struct\Proto;
+
+const NULLMARK   = '__NULL__';
+const UNDEFMARK  = '__UNDEF__';
+const EXISTSMARK = '__EXISTS__';
+
+// Sentinel distinguishing "key absent" from "value is null" in getpath.
+final class Missing
+{
+    private static ?Missing $instance = null;
+
+    public static function get(): Missing
+    {
+        if (self::$instance === null) {
+            self::$instance = new Missing();
+        }
+        return self::$instance;
+    }
+}
+
+// Default corpus path: build/test/test.json relative to the repo root.
+function default_test_file(): string
+{
+    return __DIR__ . '/../../../build/test/test.json';
+}
+
+final class TestProvider
+{
+    /** @var mixed */
+    public $spec;
+
+    /** @param mixed $spec */
+    public function __construct($spec)
+    {
+        $this->spec = $spec;
+    }
+
+    public static function load(?string $testfile = null): TestProvider
+    {
+        $file = $testfile ?? default_test_file();
+        $txt = file_get_contents($file);
+        if ($txt === false) {
+            throw new \Exception("Unable to read test file at $file");
+        }
+        // Decode objects as ordered assoc arrays (key order preserved).
+        return new TestProvider(json_decode($txt, true));
+    }
+
+    /** @return mixed */
+    public function raw()
+    {
+        return $this->spec;
+    }
+
+    /**
+     * @return array<string,mixed>
+     */
+    private function fnNode(string $fn): array
+    {
+        $node = null;
+        if (is_array($this->spec) && array_key_exists('struct', $this->spec)
+            && is_array($this->spec['struct']) && array_key_exists($fn, $this->spec['struct'])) {
+            $node = $this->spec['struct'][$fn];
+        } elseif (is_array($this->spec) && array_key_exists($fn, $this->spec)) {
+            $node = $this->spec[$fn];
+        }
+        if ($node === null) {
+            throw new \Exception("Unknown function: $fn");
+        }
+        return $node;
+    }
+
+    /**
+     * @return string[]
+     */
+    public function functions(): array
+    {
+        $root = (is_array($this->spec) && array_key_exists('struct', $this->spec))
+            ? $this->spec['struct']
+            : $this->spec;
+        $out = [];
+        foreach (array_keys($root) as $k) {
+            if (is_group_bag($root[$k]) || has_groups($root[$k])) {
+                $out[] = (string)$k;
+            }
+        }
+        return $out;
+    }
+
+    /**
+     * @return string[]
+     */
+    public function groups(string $fn): array
+    {
+        $node = $this->fnNode($fn);
+        $out = [];
+        foreach (array_keys($node) as $k) {
+            if ($k !== 'name' && is_group_bag($node[$k])) {
+                $out[] = (string)$k;
+            }
+        }
+        return $out;
+    }
+
+    /**
+     * @return array<int,array<string,mixed>>
+     */
+    public function entries(string $fn, ?string $group = null): array
+    {
+        $node = $this->fnNode($fn);
+        $groups = $group !== null ? [$group] : $this->groups($fn);
+        $out = [];
+        foreach ($groups as $g) {
+            $bag = $node[$g] ?? null;
+            if (!is_group_bag($bag)) {
+                continue;
+            }
+            $set = $bag['set'];
+            $n = count($set);
+            for ($i = 0; $i < $n; $i++) {
+                $out[] = normalize($fn, $g, $i, $set[$i]);
+            }
+        }
+        return $out;
+    }
+}
+
+// A "list" array is one whose keys are 0..n-1 sequential. Otherwise (incl.
+// empty assoc test we treat empties as lists) it is a map.
+function is_list_array(array $v): bool
+{
+    if ($v === []) {
+        return true;
+    }
+    return array_keys($v) === range(0, count($v) - 1);
+}
+
+// A group bag is a map with a `set` list.
+/** @param mixed $v */
+function is_group_bag($v): bool
+{
+    return is_array($v) && !is_list_array($v)
+        && array_key_exists('set', $v) && is_array($v['set']) && is_list_array($v['set']);
+}
+
+// A function node has at least one child group bag.
+/** @param mixed $v */
+function has_groups($v): bool
+{
+    if (!is_array($v) || is_list_array($v)) {
+        return false;
+    }
+    foreach (array_keys($v) as $k) {
+        if ($k !== 'name' && is_group_bag($v[$k])) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * @param array<string,mixed> $raw
+ * @return array<string,mixed>
+ */
+function normalize(string $fn, string $group, int $index, array $raw): array
+{
+    return [
+        'function' => $fn,
+        'group'    => $group,
+        'index'    => $index,
+        'id'       => (array_key_exists('id', $raw) && $raw['id'] !== null) ? (string)$raw['id'] : null,
+        'doc'      => array_key_exists('doc', $raw) && $raw['doc'] === true,
+        'client'   => (array_key_exists('client', $raw) && $raw['client'] !== null) ? (string)$raw['client'] : null,
+        'input'    => resolve_input($raw),
+        'expect'   => resolve_expect($raw),
+        'raw'      => $raw,
+    ];
+}
+
+/**
+ * @param array<string,mixed> $raw
+ * @return array<string,mixed>
+ */
+function resolve_input(array $raw): array
+{
+    if (array_key_exists('ctx', $raw)) {
+        return ['kind' => 'ctx', 'ctx' => $raw['ctx']];
+    }
+    if (array_key_exists('args', $raw)) {
+        return ['kind' => 'args', 'args' => $raw['args']];
+    }
+    return ['kind' => 'in', 'in' => array_key_exists('in', $raw) ? $raw['in'] : null];
+}
+
+/**
+ * @param mixed $err
+ * @return array<string,mixed>
+ */
+function parse_err($err): array
+{
+    if ($err === true) {
+        return ['any' => true, 'text' => null, 'regex' => false];
+    }
+    if (is_string($err)) {
+        if (preg_match('/^\/(.+)\/$/', $err, $m)) {
+            return ['any' => false, 'text' => $m[1], 'regex' => true];
+        }
+        return ['any' => false, 'text' => $err, 'regex' => false];
+    }
+    // Non-true, non-string err spec: treat as "any error".
+    return ['any' => true, 'text' => null, 'regex' => false];
+}
+
+/**
+ * @param array<string,mixed> $raw
+ * @return array<string,mixed>
+ */
+function resolve_expect(array $raw): array
+{
+    $hasMatch = array_key_exists('match', $raw);
+    $matchPart = $hasMatch ? $raw['match'] : null;
+    if (array_key_exists('err', $raw)) {
+        $e = ['kind' => 'error', 'error' => parse_err($raw['err'])];
+        if ($hasMatch) {
+            $e['match'] = $matchPart;
+        }
+        return $e;
+    }
+    if (array_key_exists('out', $raw)) {
+        $e = ['kind' => 'value', 'value' => $raw['out']];
+        if ($hasMatch) {
+            $e['match'] = $matchPart;
+        }
+        return $e;
+    }
+    if ($hasMatch) {
+        return ['kind' => 'match', 'match' => $raw['match']];
+    }
+    return ['kind' => 'absent'];
+}
+
+// ─── pure comparison helpers ───────────────────────────────────────────────
+
+/** @param mixed $x */
+function stringify($x): string
+{
+    if (is_string($x)) {
+        return $x;
+    }
+    return json_encode($x);
+}
+
+/**
+ * @param mixed $x
+ * @return mixed
+ */
+function norm_null($x)
+{
+    if ($x === NULLMARK || $x === null) {
+        return null;
+    }
+    if (is_array($x)) {
+        $o = [];
+        foreach ($x as $k => $v) {
+            $o[$k] = norm_null($v);
+        }
+        return $o;
+    }
+    return $x;
+}
+
+/**
+ * @param mixed $x
+ * @return mixed
+ */
+function norm_mark($x)
+{
+    if ($x === NULLMARK) {
+        return null;
+    }
+    if (is_array($x)) {
+        $o = [];
+        foreach ($x as $k => $v) {
+            $o[$k] = norm_mark($v);
+        }
+        return $o;
+    }
+    return $x;
+}
+
+/**
+ * @param mixed $check
+ * @param mixed $base
+ */
+function matchval($check, $base): bool
+{
+    if ($check === $base) {
+        return true;
+    }
+    if (is_string($check)) {
+        $basestr = stringify($base);
+        if (preg_match('/^\/(.+)\/$/', $check, $m)) {
+            return preg_match('/' . $m[1] . '/', $basestr) === 1;
+        }
+        return mb_stripos($basestr, $check) !== false;
+    }
+    if (is_callable($check)) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * @param mixed $expected
+ * @param mixed $actual
+ */
+function equal($expected, $actual): bool
+{
+    return deep_eq(norm_null($expected), norm_null($actual));
+}
+
+// Strict variant for the runner's `{ null: false }` functions, where an absent
+// value is distinct from JSON null. Only __NULL__ is normalized.
+/**
+ * @param mixed $expected
+ * @param mixed $actual
+ */
+function equal_strict($expected, $actual): bool
+{
+    return deep_eq(norm_mark($expected), norm_mark($actual));
+}
+
+/**
+ * @param mixed $a
+ * @param mixed $b
+ */
+function deep_eq($a, $b): bool
+{
+    if ($a === $b) {
+        return true;
+    }
+    if (is_array($a) && is_array($b)) {
+        $al = is_list_array($a);
+        $bl = is_list_array($b);
+        if ($al !== $bl) {
+            return false;
+        }
+        if ($al) {
+            if (count($a) !== count($b)) {
+                return false;
+            }
+            for ($i = 0; $i < count($a); $i++) {
+                if (!array_key_exists($i, $b) || !deep_eq($a[$i], $b[$i])) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        $ak = array_keys($a);
+        $bk = array_keys($b);
+        if (count($ak) !== count($bk)) {
+            return false;
+        }
+        foreach ($ak as $k) {
+            if (!array_key_exists($k, $b) || !deep_eq($a[$k], $b[$k])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return false;
+}
+
+/**
+ * @param array<string,mixed> $check ErrorCheck {any,text,regex}
+ */
+function error_matches(array $check, string $message): bool
+{
+    if ($check['any']) {
+        return true;
+    }
+    if ($check['text'] === null) {
+        return false;
+    }
+    if ($check['regex']) {
+        return preg_match('/' . $check['text'] . '/', $message) === 1;
+    }
+    return mb_stripos(mb_strtolower($message), mb_strtolower((string)$check['text'])) !== false;
+}
+
+// Partial structural match: every leaf of `check` must match `base` at its path.
+/**
+ * @param mixed $check
+ * @param mixed $base
+ * @return array<string,mixed>
+ */
+function struct_match($check, $base): array
+{
+    $result = ['ok' => true];
+    walk_leaves($check, [], function ($val, $path) use (&$result, $base) {
+        if (!$result['ok']) {
+            return;
+        }
+        $baseval = sm_getpath($base, $path);
+        if ($baseval === $val) {
+            return;
+        }
+        if ($val === UNDEFMARK && $baseval === Missing::get()) {
+            return;
+        }
+        if ($val === EXISTSMARK && $baseval !== Missing::get() && $baseval !== null) {
+            return;
+        }
+        if (!matchval($val, $baseval === Missing::get() ? null : $baseval)) {
+            $result = [
+                'ok'       => false,
+                'path'     => $path,
+                'expected' => $val,
+                'actual'   => $baseval === Missing::get() ? null : $baseval,
+            ];
+        }
+    });
+    return $result;
+}
+
+/** @param mixed $v */
+function is_node($v): bool
+{
+    return is_array($v);
+}
+
+/**
+ * @param mixed $node
+ * @param string[] $path
+ */
+function walk_leaves($node, array $path, callable $fn): void
+{
+    if (is_array($node) && is_list_array($node)) {
+        foreach ($node as $i => $v) {
+            walk_leaves($v, array_merge($path, [(string)$i]), $fn);
+        }
+    } elseif (is_node($node)) {
+        foreach ($node as $k => $v) {
+            walk_leaves($v, array_merge($path, [(string)$k]), $fn);
+        }
+    } else {
+        $fn($node, $path);
+    }
+}
+
+/**
+ * @param mixed $store
+ * @param string[] $path
+ * @return mixed Missing sentinel if absent.
+ */
+function sm_getpath($store, array $path)
+{
+    $cur = $store;
+    foreach ($path as $key) {
+        if ($cur === null) {
+            return Missing::get();
+        }
+        if (is_array($cur)) {
+            if (is_list_array($cur)) {
+                $idx = (int)$key;
+                if (!array_key_exists($idx, $cur)) {
+                    return Missing::get();
+                }
+                $cur = $cur[$idx];
+            } else {
+                if (!array_key_exists($key, $cur)) {
+                    return Missing::get();
+                }
+                $cur = $cur[$key];
+            }
+        } else {
+            return Missing::get();
+        }
+    }
+    return $cur;
+}
diff --git a/test/proto/php/smoke.php b/test/proto/php/smoke.php
new file mode 100644
index 0000000..ff99a4d
--- /dev/null
+++ b/test/proto/php/smoke.php
@@ -0,0 +1,86 @@
+<?php
+
+// Smoke test for the PHP test provider port. Prints summary stats that must
+// match the canonical TS output documented in PROVIDER work.
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/provider.php';
+
+use function Voxgig\Struct\Proto\equal;
+use function Voxgig\Struct\Proto\equal_strict;
+use function Voxgig\Struct\Proto\error_matches;
+use function Voxgig\Struct\Proto\struct_match;
+
+use Voxgig\Struct\Proto\TestProvider;
+
+function bool_str($b): string
+{
+    return $b ? 'true' : 'false';
+}
+
+function val_str($v): string
+{
+    if ($v === null) {
+        return 'null';
+    }
+    if (is_bool($v)) {
+        return bool_str($v);
+    }
+    if (is_string($v)) {
+        return $v;
+    }
+    return json_encode($v);
+}
+
+$prov = TestProvider::load();
+
+$fns = $prov->functions();
+echo 'functions: ' . implode(', ', $fns) . "\n";
+
+$total = 0;
+$expectKinds = [];
+$inputKinds = [];
+foreach ($fns as $fn) {
+    foreach ($prov->entries($fn) as $entry) {
+        $total++;
+        $ek = $entry['expect']['kind'];
+        $ik = $entry['input']['kind'];
+        $expectKinds[$ek] = ($expectKinds[$ek] ?? 0) + 1;
+        $inputKinds[$ik] = ($inputKinds[$ik] ?? 0) + 1;
+    }
+}
+
+echo 'total entries: ' . $total . "\n";
+
+$ekParts = [];
+$ekKeys = array_keys($expectKinds);
+sort($ekKeys);
+foreach ($ekKeys as $k) {
+    $ekParts[] = "$k={$expectKinds[$k]}";
+}
+echo 'expect kinds: ' . implode(', ', $ekParts) . "\n";
+
+$ikParts = [];
+$ikKeys = array_keys($inputKinds);
+sort($ikKeys);
+foreach ($ikKeys as $k) {
+    $ikParts[] = "$k={$inputKinds[$k]}";
+}
+echo 'input kinds: ' . implode(', ', $ikParts) . "\n";
+
+$e = $prov->entries('getpath', 'basic')[0];
+echo 'getpath/basic[0]: '
+    . "id={$e['id']}, doc=" . bool_str($e['doc']) . ', '
+    . "input.kind={$e['input']['kind']}, input.in=" . val_str($e['input']['in']) . ', '
+    . "expect.kind={$e['expect']['kind']}, expect.value=" . val_str($e['expect']['value']) . "\n";
+
+// ─── helper sanity checks ──────────────────────────────────────────────────
+echo 'equal(null, missing) lenient: ' . bool_str(equal(null, null)) . "\n";
+echo 'equal_strict distinguishes null vs __NULL__-collapse: '
+    . bool_str(equal_strict(null, '__NULL__')) . ' / '
+    . bool_str(equal_strict(null, 1)) . "\n";
+echo 'error_matches substring case-insensitive: '
+    . bool_str(error_matches(['any' => false, 'text' => 'Foo', 'regex' => false], 'a foobar error')) . "\n";
+$sm = struct_match(['a' => ['b' => 2]], ['a' => ['b' => 3]]);
+echo 'struct_match failure: ' . json_encode($sm) . "\n";
diff --git a/test/proto/python/provider.py b/test/proto/python/provider.py
new file mode 100644
index 0000000..8a6ec44
--- /dev/null
+++ b/test/proto/python/provider.py
@@ -0,0 +1,268 @@
+# Test Provider (prototype) — Python port of the canonical ts/provider.ts.
+#
+# Reads the shared corpus (build/test/test.json) and hands test code clean,
+# normalized cases. It is NOT a test runner: it never calls the subject and
+# never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+#
+# Zero runtime dependencies (stdlib only), matching repo policy.
+
+import json
+import os
+import re
+from typing import Any
+
+NULLMARK = '__NULL__'
+UNDEFMARK = '__UNDEF__'
+EXISTSMARK = '__EXISTS__'
+
+# Sentinel distinguishing "key absent" from "value is None" in getpath.
+_MISSING = object()
+
+
+# Default corpus path: build/test/test.json relative to the repo root.
+def default_test_file() -> str:
+    here = os.path.dirname(os.path.abspath(__file__))  # test/proto/python
+    return os.path.join(here, '..', '..', '..', 'build', 'test', 'test.json')
+
+
+class TestProvider:
+
+    def __init__(self, spec: Any):
+        self.spec = spec
+
+    @classmethod
+    def load(cls, testfile: str | None = None) -> 'TestProvider':
+        file = testfile if testfile is not None else default_test_file()
+        with open(file, encoding='utf-8') as f:
+            return cls(json.load(f))
+
+    def raw(self) -> Any:
+        return self.spec
+
+    def _fn_node(self, fn: str) -> dict[str, Any]:
+        root = self.spec.get('struct') if isinstance(self.spec, dict) else None
+        node = None
+        if isinstance(root, dict) and fn in root:
+            node = root[fn]
+        elif isinstance(self.spec, dict) and fn in self.spec:
+            node = self.spec[fn]
+        if node is None:
+            raise ValueError(f'Unknown function: {fn}')
+        return node
+
+    def functions(self) -> list[str]:
+        root = self.spec.get('struct') if isinstance(self.spec, dict) else None
+        if not isinstance(root, dict):
+            root = self.spec
+        return [k for k in root.keys() if is_group_bag(root[k]) or has_groups(root[k])]
+
+    def groups(self, fn: str) -> list[str]:
+        node = self._fn_node(fn)
+        return [k for k in node.keys() if k != 'name' and is_group_bag(node[k])]
+
+    def entries(self, fn: str, group: str | None = None) -> list[dict[str, Any]]:
+        node = self._fn_node(fn)
+        groups = [group] if group is not None else self.groups(fn)
+        out: list[dict[str, Any]] = []
+        for g in groups:
+            bag = node[g]
+            if not is_group_bag(bag):
+                continue
+            test_set = bag['set']
+            for i in range(len(test_set)):
+                out.append(normalize(fn, g, i, test_set[i]))
+        return out
+
+
+# A group bag is a map with a `set` list.
+def is_group_bag(v: Any) -> bool:
+    return isinstance(v, dict) and isinstance(v.get('set'), list)
+
+
+# A function node has at least one child group bag.
+def has_groups(v: Any) -> bool:
+    return isinstance(v, dict) and any(
+        k != 'name' and is_group_bag(v[k]) for k in v.keys()
+    )
+
+
+def normalize(fn: str, group: str, index: int, raw: dict[str, Any]) -> dict[str, Any]:
+    return {
+        'function': fn,
+        'group': group,
+        'index': index,
+        'id': str(raw['id']) if raw.get('id') is not None else None,
+        'doc': raw.get('doc') is True,
+        'client': str(raw['client']) if raw.get('client') is not None else None,
+        'input': resolve_input(raw),
+        'expect': resolve_expect(raw),
+        'raw': raw,
+    }
+
+
+def has(raw: dict[str, Any], key: str) -> bool:
+    return key in raw
+
+
+def resolve_input(raw: dict[str, Any]) -> dict[str, Any]:
+    if has(raw, 'ctx'):
+        return {'kind': 'ctx', 'ctx': raw['ctx']}
+    if has(raw, 'args'):
+        return {'kind': 'args', 'args': raw['args']}
+    return {'kind': 'in', 'in': raw['in'] if has(raw, 'in') else None}
+
+
+def parse_err(err: Any) -> dict[str, Any]:
+    if err is True:
+        return {'any': True, 'text': None, 'regex': False}
+    if isinstance(err, str):
+        m = re.match(r'^/(.+)/$', err)
+        if m:
+            return {'any': False, 'text': m.group(1), 'regex': True}
+        return {'any': False, 'text': err, 'regex': False}
+    # Non-true, non-string err spec: treat as "any error".
+    return {'any': True, 'text': None, 'regex': False}
+
+
+def resolve_expect(raw: dict[str, Any]) -> dict[str, Any]:
+    match_part = raw['match'] if has(raw, 'match') else None
+    if has(raw, 'err'):
+        return {'kind': 'error', 'error': parse_err(raw['err']), 'match': match_part}
+    if has(raw, 'out'):
+        return {'kind': 'value', 'value': raw['out'], 'match': match_part}
+    if has(raw, 'match'):
+        return {'kind': 'match', 'match': raw['match']}
+    return {'kind': 'absent'}
+
+
+# ─── pure comparison helpers ───────────────────────────────────────────────
+
+def stringify(x: Any) -> str:
+    return x if isinstance(x, str) else json.dumps(x)
+
+
+def _norm_null(x: Any) -> Any:
+    if x == NULLMARK or x is None:
+        return None
+    if isinstance(x, list):
+        return [_norm_null(v) for v in x]
+    if isinstance(x, dict):
+        return {k: _norm_null(v) for k, v in x.items()}
+    return x
+
+
+def matchval(check: Any, base: Any) -> bool:
+    if check == base:
+        return True
+    if isinstance(check, str):
+        basestr = stringify(base)
+        rem = re.match(r'^/(.+)/$', check)
+        if rem:
+            return re.search(rem.group(1), basestr) is not None
+        return check.lower() in basestr.lower()
+    if callable(check):
+        return True
+    return False
+
+
+def equal(expected: Any, actual: Any) -> bool:
+    return _deep_eq(_norm_null(expected), _norm_null(actual))
+
+
+# Strict variant for the runner's `{ null: false }` functions, where an absent
+# value is distinct from JSON null. Only __NULL__ is normalized.
+def equal_strict(expected: Any, actual: Any) -> bool:
+    return _deep_eq(_norm_mark(expected), _norm_mark(actual))
+
+
+def _norm_mark(x: Any) -> Any:
+    if x == NULLMARK:
+        return None
+    if isinstance(x, list):
+        return [_norm_mark(v) for v in x]
+    if isinstance(x, dict):
+        return {k: _norm_mark(v) for k, v in x.items()}
+    return x
+
+
+def _deep_eq(a: Any, b: Any) -> bool:
+    # Guard against Python's bool/int equivalence (True == 1) to mirror JS ===.
+    if isinstance(a, bool) != isinstance(b, bool):
+        return False
+    if a is b:
+        return True
+    if isinstance(a, list) and isinstance(b, list):
+        return len(a) == len(b) and all(_deep_eq(v, b[i]) for i, v in enumerate(a))
+    if isinstance(a, dict) and isinstance(b, dict):
+        ak = list(a.keys())
+        bk = list(b.keys())
+        return len(ak) == len(bk) and all(k in b and _deep_eq(a[k], b[k]) for k in ak)
+    if isinstance(a, list) or isinstance(b, list):
+        return False
+    if isinstance(a, dict) or isinstance(b, dict):
+        return False
+    return a == b
+
+
+def error_matches(check: dict[str, Any], message: str) -> bool:
+    if check.get('any'):
+        return True
+    text = check.get('text')
+    if text is None:
+        return False
+    if check.get('regex'):
+        return re.search(text, message) is not None
+    return text.lower() in message.lower()
+
+
+# Partial structural match: every leaf of `check` must match `base` at its path.
+def struct_match(check: Any, base: Any) -> dict[str, Any]:
+    result: dict[str, Any] = {'ok': True}
+
+    def visit(val: Any, path: list[str]) -> None:
+        nonlocal result
+        if not result['ok']:
+            return
+        baseval = _getpath(base, path)
+        if baseval is not _MISSING and baseval == val:
+            return
+        if val == UNDEFMARK and baseval is _MISSING:
+            return
+        if val == EXISTSMARK and baseval is not _MISSING and baseval is not None:
+            return
+        compare_base = None if baseval is _MISSING else baseval
+        if not matchval(val, compare_base):
+            result = {'ok': False, 'path': path, 'expected': val, 'actual': compare_base}
+
+    _walk_leaves(check, [], visit)
+    return result
+
+
+def _is_node(v: Any) -> bool:
+    return isinstance(v, (dict, list))
+
+
+def _walk_leaves(node: Any, path: list[str], fn) -> None:
+    if isinstance(node, list):
+        for i, v in enumerate(node):
+            _walk_leaves(v, path + [str(i)], fn)
+    elif isinstance(node, dict):
+        for k in node.keys():
+            _walk_leaves(node[k], path + [k], fn)
+    else:
+        fn(node, path)
+
+
+def _getpath(store: Any, path: list[str]) -> Any:
+    cur = store
+    for key in path:
+        if cur is None or cur is _MISSING:
+            return _MISSING
+        if isinstance(cur, list):
+            idx = int(key)
+            cur = cur[idx] if 0 <= idx < len(cur) else _MISSING
+        elif isinstance(cur, dict):
+            cur = cur[key] if key in cur else _MISSING
+        else:
+            return _MISSING
+    return cur
diff --git a/test/proto/python/smoke.py b/test/proto/python/smoke.py
new file mode 100644
index 0000000..68e5f3c
--- /dev/null
+++ b/test/proto/python/smoke.py
@@ -0,0 +1,63 @@
+# Smoke test for the Python test provider port. Prints summary stats that must
+# match the canonical TS output documented in PROVIDER work.
+
+from provider import (
+    TestProvider,
+    equal,
+    equal_strict,
+    error_matches,
+    struct_match,
+)
+
+
+def main() -> None:
+    prov = TestProvider.load()
+
+    fns = prov.functions()
+    print('functions:', ', '.join(fns))
+
+    total = 0
+    expect_kinds: dict[str, int] = {}
+    input_kinds: dict[str, int] = {}
+    for fn in fns:
+        for entry in prov.entries(fn):
+            total += 1
+            ek = entry['expect']['kind']
+            ik = entry['input']['kind']
+            expect_kinds[ek] = expect_kinds.get(ek, 0) + 1
+            input_kinds[ik] = input_kinds.get(ik, 0) + 1
+
+    print('total entries:', total)
+    print(
+        'expect kinds:',
+        ', '.join(f'{k}={expect_kinds[k]}' for k in sorted(expect_kinds)),
+    )
+    print(
+        'input kinds:',
+        ', '.join(f'{k}={input_kinds[k]}' for k in sorted(input_kinds)),
+    )
+
+    e = prov.entries('getpath', 'basic')[0]
+    print(
+        'getpath/basic[0]:',
+        f"id={e['id']}, doc={e['doc']}, "
+        f"input.kind={e['input']['kind']}, input.in={e['input']['in']}, "
+        f"expect.kind={e['expect']['kind']}, expect.value={e['expect']['value']}",
+    )
+
+    # ─── helper sanity checks ──────────────────────────────────────────────
+    print('equal(None, missing) lenient:', equal(None, {}.get('x')))
+    print(
+        'equal_strict distinguishes None vs __NULL__-collapse:',
+        equal_strict(None, '__NULL__'), '/', equal_strict(None, 1),
+    )
+    print(
+        'error_matches substring case-insensitive:',
+        error_matches({'any': False, 'text': 'Foo', 'regex': False}, 'a foobar error'),
+    )
+    sm = struct_match({'a': {'b': 2}}, {'a': {'b': 3}})
+    print('struct_match failure:', sm)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/test/proto/ruby/provider.rb b/test/proto/ruby/provider.rb
new file mode 100644
index 0000000..6e7377e
--- /dev/null
+++ b/test/proto/ruby/provider.rb
@@ -0,0 +1,286 @@
+# Test Provider (prototype) — Ruby port.
+#
+# Reads the shared corpus (build/test/test.json) and hands test code clean,
+# normalized cases. It is NOT a test runner: it never calls the subject and
+# never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+#
+# Zero runtime dependencies (Ruby stdlib only).
+
+require 'json'
+
+class TestProvider
+  NULLMARK = '__NULL__'.freeze
+  UNDEFMARK = '__UNDEF__'.freeze
+  EXISTSMARK = '__EXISTS__'.freeze
+
+  attr_reader :spec
+
+  def initialize(spec)
+    @spec = spec
+  end
+
+  # Default corpus path: build/test/test.json relative to the repo root.
+  def self.default_test_file
+    File.join(__dir__, '..', '..', '..', 'build', 'test', 'test.json')
+  end
+
+  def self.load(path = nil)
+    file = path || default_test_file
+    new(JSON.parse(File.read(file)))
+  end
+
+  def raw
+    @spec
+  end
+
+  def functions
+    root = root_node
+    root.keys.select { |k| self.class.group_bag?(root[k]) || self.class.has_groups?(root[k]) }
+  end
+
+  def groups(fn)
+    node = fn_node(fn)
+    node.keys.select { |k| k != 'name' && self.class.group_bag?(node[k]) }
+  end
+
+  def entries(fn, group = nil)
+    node = fn_node(fn)
+    gs = group.nil? ? groups(fn) : [group]
+    out = []
+    gs.each do |g|
+      bag = node[g]
+      next unless self.class.group_bag?(bag)
+
+      set = bag['set']
+      set.each_with_index do |raw_entry, i|
+        out << self.class.normalize(fn, g, i, raw_entry)
+      end
+    end
+    out
+  end
+
+  private
+
+  def root_node
+    (@spec.is_a?(Hash) && @spec['struct']) || @spec
+  end
+
+  def fn_node(fn)
+    node = nil
+    node = @spec['struct'][fn] if @spec.is_a?(Hash) && @spec['struct'].is_a?(Hash)
+    node = @spec[fn] if node.nil? && @spec.is_a?(Hash)
+    raise "Unknown function: #{fn}" if node.nil?
+
+    node
+  end
+
+  # ─── structural predicates ────────────────────────────────────────────────
+
+  # A group bag is a map with a `set` array.
+  def self.group_bag?(v)
+    v.is_a?(Hash) && v['set'].is_a?(Array)
+  end
+
+  # A function node has at least one child group bag.
+  def self.has_groups?(v)
+    v.is_a?(Hash) && v.keys.any? { |k| k != 'name' && group_bag?(v[k]) }
+  end
+
+  # ─── normalization ────────────────────────────────────────────────────────
+
+  def self.normalize(fn, group, index, raw)
+    {
+      function: fn,
+      group: group,
+      index: index,
+      id: raw.key?('id') && !raw['id'].nil? ? raw['id'].to_s : nil,
+      doc: raw['doc'] == true,
+      client: raw.key?('client') && !raw['client'].nil? ? raw['client'].to_s : nil,
+      input: resolve_input(raw),
+      expect: resolve_expect(raw),
+      raw: raw
+    }
+  end
+
+  def self.resolve_input(raw)
+    return { kind: 'ctx', ctx: raw['ctx'] } if raw.key?('ctx')
+    return { kind: 'args', args: raw['args'] } if raw.key?('args')
+
+    { kind: 'in', in: raw.key?('in') ? raw['in'] : nil }
+  end
+
+  def self.parse_err(err)
+    return { any: true, text: nil, regex: false } if err == true
+
+    if err.is_a?(String)
+      m = err.match(%r{\A/(.+)/\z})
+      return { any: false, text: m[1], regex: true } if m
+
+      return { any: false, text: err, regex: false }
+    end
+
+    # Non-true, non-string err spec: treat as "any error".
+    { any: true, text: nil, regex: false }
+  end
+
+  def self.resolve_expect(raw)
+    match_part = raw.key?('match') ? raw['match'] : nil
+    return { kind: 'error', error: parse_err(raw['err']), match: match_part } if raw.key?('err')
+    return { kind: 'value', value: raw['out'], match: match_part } if raw.key?('out')
+    return { kind: 'match', match: raw['match'] } if raw.key?('match')
+
+    { kind: 'absent' }
+  end
+
+  # ─── pure comparison helpers ──────────────────────────────────────────────
+
+  def self.stringify(x)
+    x.is_a?(String) ? x : x.to_json
+  end
+
+  def self.norm_null(x)
+    return nil if x == NULLMARK || x.nil?
+    return x.map { |v| norm_null(v) } if x.is_a?(Array)
+
+    if x.is_a?(Hash)
+      o = {}
+      x.each_key { |k| o[k] = norm_null(x[k]) }
+      return o
+    end
+    x
+  end
+
+  def self.norm_mark(x)
+    return nil if x == NULLMARK
+    return x.map { |v| norm_mark(v) } if x.is_a?(Array)
+
+    if x.is_a?(Hash)
+      o = {}
+      x.each_key { |k| o[k] = norm_mark(x[k]) }
+      return o
+    end
+    x
+  end
+
+  def self.deep_eq(a, b)
+    return true if a.equal?(b)
+    # Guard true/false vs 1: Ruby true != 1 already, so == is safe here.
+    return true if a == b && same_kind?(a, b)
+
+    if a.is_a?(Array) && b.is_a?(Array)
+      return false unless a.length == b.length
+
+      return a.each_index.all? { |i| deep_eq(a[i], b[i]) }
+    end
+
+    if a.is_a?(Hash) && b.is_a?(Hash)
+      return false unless a.keys.length == b.keys.length
+
+      return a.keys.all? { |k| b.key?(k) && deep_eq(a[k], b[k]) }
+    end
+
+    false
+  end
+
+  # Distinguish e.g. true vs 1, nil vs false where Ruby == would already
+  # separate them, but be explicit for primitive identity comparisons.
+  def self.same_kind?(a, b)
+    return a.equal?(b) if [true, false, nil].include?(a) || [true, false, nil].include?(b)
+
+    true
+  end
+  private_class_method :same_kind?
+
+  def self.matchval(check, base)
+    return true if check == base && same_kind?(check, base)
+
+    if check.is_a?(String)
+      basestr = stringify(base)
+      m = check.match(%r{\A/(.+)/\z})
+      return Regexp.new(m[1]).match?(basestr) if m
+
+      return basestr.downcase.include?(check.downcase)
+    end
+
+    return true if check.respond_to?(:call)
+
+    false
+  end
+
+  def self.equal(expected, actual)
+    deep_eq(norm_null(expected), norm_null(actual))
+  end
+
+  # Strict variant for the runner's `{ null: false }` functions, where an absent
+  # value (undefined) is distinct from JSON null. Only __NULL__ is normalized.
+  def self.equal_strict(expected, actual)
+    deep_eq(norm_mark(expected), norm_mark(actual))
+  end
+
+  def self.error_matches(check, message)
+    return true if check[:any]
+    return false if check[:text].nil?
+    return Regexp.new(check[:text]).match?(message) if check[:regex]
+
+    message.downcase.include?(check[:text].downcase)
+  end
+
+  def self.node?(v)
+    v.is_a?(Hash) || v.is_a?(Array)
+  end
+
+  def self.walk_leaves(node, path, &block)
+    if node.is_a?(Array)
+      node.each_with_index { |v, i| walk_leaves(v, path + [i.to_s], &block) }
+    elsif node.is_a?(Hash)
+      node.each_key { |k| walk_leaves(node[k], path + [k], &block) }
+    else
+      block.call(node, path)
+    end
+  end
+
+  # Sentinel distinguishing JS `undefined` (absent) from JSON null (present nil).
+  UNDEF = Object.new.freeze
+
+  def self.getpath(store, path)
+    cur = store
+    path.each do |key|
+      return UNDEF if cur.nil? || cur.equal?(UNDEF)
+
+      if cur.is_a?(Array)
+        idx = key.to_i
+        return UNDEF if idx.negative? || idx >= cur.length
+
+        cur = cur[idx]
+      elsif cur.is_a?(Hash)
+        return UNDEF unless cur.key?(key)
+
+        cur = cur[key]
+      else
+        return UNDEF
+      end
+    end
+    cur
+  end
+
+  # Partial structural match: every leaf of `check` must match `base` at its path.
+  def self.struct_match(check, base)
+    result = { ok: true }
+    walk_leaves(check, []) do |val, path|
+      next unless result[:ok]
+
+      baseval = getpath(base, path)
+      undef_base = baseval.equal?(UNDEF)
+      actual = undef_base ? nil : baseval
+
+      next if !undef_base && baseval == val && same_kind?(baseval, val)
+      next if val == UNDEFMARK && undef_base
+      next if val == EXISTSMARK && !undef_base && !actual.nil?
+
+      unless matchval(val, actual)
+        result = { ok: false, path: path, expected: val, actual: actual }
+      end
+    end
+    result
+  end
+end
diff --git a/test/proto/ruby/smoke.rb b/test/proto/ruby/smoke.rb
new file mode 100644
index 0000000..b78cd31
--- /dev/null
+++ b/test/proto/ruby/smoke.rb
@@ -0,0 +1,33 @@
+# Smoke test for the Ruby test provider port. Prints summary stats that must
+# match the canonical TS output documented in PROVIDER.
+
+require_relative 'provider'
+
+def main
+  prov = TestProvider.load
+
+  fns = prov.functions
+  puts "functions: #{fns.join(', ')}"
+
+  total = 0
+  expect_kinds = Hash.new(0)
+  input_kinds = Hash.new(0)
+  fns.each do |fn|
+    prov.entries(fn).each do |entry|
+      total += 1
+      expect_kinds[entry[:expect][:kind]] += 1
+      input_kinds[entry[:input][:kind]] += 1
+    end
+  end
+
+  puts "total entries: #{total}"
+  puts "expect kinds: #{expect_kinds.map { |k, v| "#{k}=#{v}" }.join(', ')}"
+  puts "input kinds: #{input_kinds.map { |k, v| "#{k}=#{v}" }.join(', ')}"
+
+  e = prov.entries('getpath', 'basic')[0]
+  puts "getpath/basic[0]: id=#{e[:id]}, doc=#{e[:doc]}, " \
+       "input.kind=#{e[:input][:kind]}, " \
+       "expect.kind=#{e[:expect][:kind]}, expect.value=#{e[:expect][:value]}"
+end
+
+main if __FILE__ == $PROGRAM_NAME
diff --git a/test/proto/rust/Cargo.lock b/test/proto/rust/Cargo.lock
new file mode 100644
index 0000000..7cf9bdd
--- /dev/null
+++ b/test/proto/rust/Cargo.lock
@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "structproto"
+version = "0.1.0"
diff --git a/test/proto/rust/Cargo.toml b/test/proto/rust/Cargo.toml
new file mode 100644
index 0000000..f6cf93f
--- /dev/null
+++ b/test/proto/rust/Cargo.toml
@@ -0,0 +1,19 @@
+[package]
+name = "structproto"
+version = "0.1.0"
+edition = "2021"
+description = "Test Provider (prototype) — Rust port of test/proto/ts/provider.ts"
+license = "MIT"
+publish = false
+
+[lib]
+name = "structproto"
+path = "src/lib.rs"
+
+[dependencies]
+# DEPENDENCY-FREE: this prototype uses NO third-party crates. JSON is parsed by
+# a small hand-written recursive-descent parser (see the `json` module in
+# src/lib.rs); its object variant preserves key insertion order so `functions()`
+# and `groups()` return corpus order ("minor","getpath",…) rather than sorted
+# keys. Regex matching for "/re/" specs uses the tiny dependency-free matcher
+# (see the `mini_regex` module). See `// PROTOTYPE` comments for the scope.
diff --git a/test/proto/rust/examples/smoke.rs b/test/proto/rust/examples/smoke.rs
new file mode 100644
index 0000000..48a0b68
--- /dev/null
+++ b/test/proto/rust/examples/smoke.rs
@@ -0,0 +1,78 @@
+// Smoke check for the Rust Test Provider port. Loads the corpus and prints a
+// summary that must match the canonical TS reference numbers.
+
+use std::collections::BTreeMap;
+
+use structproto::{ExpectKind, InputKind, TestProvider};
+
+fn main() {
+    let provider = TestProvider::load(None);
+
+    let functions = provider.functions();
+    println!("functions: {}", functions.join(", "));
+
+    let mut total = 0usize;
+    let mut expect_counts: BTreeMap<&str, usize> = BTreeMap::new();
+    let mut input_counts: BTreeMap<&str, usize> = BTreeMap::new();
+
+    for func in &functions {
+        for entry in provider.entries(func, None) {
+            total += 1;
+            let ek = match entry.expect.kind {
+                ExpectKind::Value => "value",
+                ExpectKind::Error => "error",
+                ExpectKind::Match => "match",
+                ExpectKind::Absent => "absent",
+            };
+            *expect_counts.entry(ek).or_insert(0) += 1;
+            let ik = match entry.input.kind {
+                InputKind::In => "in",
+                InputKind::Args => "args",
+                InputKind::Ctx => "ctx",
+            };
+            *input_counts.entry(ik).or_insert(0) += 1;
+        }
+    }
+
+    println!("total entries: {}", total);
+    println!(
+        "expect kinds: value={}, absent={}, match={}, error={}",
+        expect_counts.get("value").copied().unwrap_or(0),
+        expect_counts.get("absent").copied().unwrap_or(0),
+        expect_counts.get("match").copied().unwrap_or(0),
+        expect_counts.get("error").copied().unwrap_or(0),
+    );
+    println!(
+        "input kinds: in={}, args={}, ctx={}",
+        input_counts.get("in").copied().unwrap_or(0),
+        input_counts.get("args").copied().unwrap_or(0),
+        input_counts.get("ctx").copied().unwrap_or(0),
+    );
+
+    // getpath/basic[0]
+    let basic = provider.entries("getpath", Some("basic"));
+    let e0 = &basic[0];
+    let input_kind = match e0.input.kind {
+        InputKind::In => "in",
+        InputKind::Args => "args",
+        InputKind::Ctx => "ctx",
+    };
+    let expect_kind = match e0.expect.kind {
+        ExpectKind::Value => "value",
+        ExpectKind::Error => "error",
+        ExpectKind::Match => "match",
+        ExpectKind::Absent => "absent",
+    };
+    println!(
+        "getpath/basic[0]: id={}, doc={}, input.kind={}, expect.kind={}, expect.value={}",
+        e0.id.as_deref().unwrap_or("<none>"),
+        e0.doc,
+        input_kind,
+        expect_kind,
+        e0.expect
+            .value
+            .as_ref()
+            .map(|v| v.to_string())
+            .unwrap_or_else(|| "<none>".to_string()),
+    );
+}
diff --git a/test/proto/rust/src/lib.rs b/test/proto/rust/src/lib.rs
new file mode 100644
index 0000000..8dffe16
--- /dev/null
+++ b/test/proto/rust/src/lib.rs
@@ -0,0 +1,1159 @@
+// Test Provider (prototype) — Rust port of the CANONICAL implementation
+// (../ts/provider.ts).
+//
+// Reads the shared corpus (build/test/test.json) and hands test code clean,
+// normalized cases. It is NOT a test runner: it never calls the subject and
+// never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+//
+// DEPENDENCY-FREE: this crate has NO third-party dependencies. JSON is handled
+// by the hand-written `json` module below (a `Json` value enum + recursive
+// descent parser). The object variant is a `Vec<(String, Json)>` that preserves
+// key insertion order, so `functions()`/`groups()` return the corpus order
+// (minor first) rather than sorted keys. Regex matching is provided by the tiny
+// dependency-free `mini_regex` module.
+
+use std::fs;
+use std::path::PathBuf;
+
+pub use json::Json;
+
+const NULLMARK: &str = "__NULL__";
+const UNDEFMARK: &str = "__UNDEF__";
+const EXISTSMARK: &str = "__EXISTS__";
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InputKind {
+    In,
+    Args,
+    Ctx,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ExpectKind {
+    Value,
+    Error,
+    Match,
+    Absent,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ErrorCheck {
+    pub any: bool,
+    pub text: Option<String>,
+    pub regex: bool,
+}
+
+#[derive(Debug, Clone)]
+pub struct Input {
+    pub kind: InputKind,
+    // Holds `in` OR `args` OR `ctx` as a Json, per `kind`.
+    pub value: Json,
+}
+
+#[derive(Debug, Clone)]
+pub struct Expect {
+    pub kind: ExpectKind,
+    pub value: Option<Json>,
+    pub error: Option<ErrorCheck>,
+    pub r#match: Option<Json>,
+}
+
+#[derive(Debug, Clone)]
+pub struct Entry {
+    pub function: String,
+    pub group: String,
+    pub index: usize,
+    pub id: Option<String>,
+    pub doc: bool,
+    pub client: Option<String>,
+    pub input: Input,
+    pub expect: Expect,
+    pub raw: Json,
+}
+
+#[derive(Debug, Clone)]
+pub struct MatchResult {
+    pub ok: bool,
+    pub path: Vec<String>,
+    pub expected: Option<Json>,
+    pub actual: Option<Json>,
+}
+
+// Default corpus path: build/test/test.json relative to the repo root.
+// From test/proto/rust, the repo root is three levels up.
+fn default_test_file() -> PathBuf {
+    let mut p = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    p.push("..");
+    p.push("..");
+    p.push("..");
+    p.push("build");
+    p.push("test");
+    p.push("test.json");
+    p
+}
+
+pub struct TestProvider {
+    spec: Json,
+}
+
+impl TestProvider {
+    pub fn load(testfile: Option<&str>) -> TestProvider {
+        let path: PathBuf = match testfile {
+            Some(f) => PathBuf::from(f),
+            None => default_test_file(),
+        };
+        let txt = fs::read_to_string(&path)
+            .unwrap_or_else(|e| panic!("read {:?}: {e}", path));
+        let spec: Json = json::parse(&txt).expect("parse test.json");
+        TestProvider { spec }
+    }
+
+    pub fn raw(&self) -> &Json {
+        &self.spec
+    }
+
+    // Root node: prefer spec.struct, else the spec itself.
+    fn root(&self) -> &Json {
+        match self.spec.get("struct") {
+            Some(s) => s,
+            None => &self.spec,
+        }
+    }
+
+    fn fn_node(&self, func: &str) -> &Json {
+        let node = self
+            .spec
+            .get("struct")
+            .and_then(|s| s.get(func))
+            .or_else(|| self.spec.get(func));
+        match node {
+            Some(n) => n,
+            None => panic!("Unknown function: {func}"),
+        }
+    }
+
+    pub fn functions(&self) -> Vec<String> {
+        let root = self.root();
+        match root.as_object() {
+            Some(obj) => obj
+                .iter()
+                .filter(|(_, v)| is_group_bag(v) || has_groups(v))
+                .map(|(k, _)| k.clone())
+                .collect(),
+            None => Vec::new(),
+        }
+    }
+
+    pub fn groups(&self, func: &str) -> Vec<String> {
+        let node = self.fn_node(func);
+        match node.as_object() {
+            Some(obj) => obj
+                .iter()
+                .filter(|(k, v)| k.as_str() != "name" && is_group_bag(v))
+                .map(|(k, _)| k.clone())
+                .collect(),
+            None => Vec::new(),
+        }
+    }
+
+    pub fn entries(&self, func: &str, group: Option<&str>) -> Vec<Entry> {
+        let node = self.fn_node(func);
+        let groups: Vec<String> = match group {
+            Some(g) => vec![g.to_string()],
+            None => self.groups(func),
+        };
+        let mut out: Vec<Entry> = Vec::new();
+        for g in &groups {
+            let bag = match node.get(g) {
+                Some(b) => b,
+                None => continue,
+            };
+            if !is_group_bag(bag) {
+                continue;
+            }
+            if let Some(set) = bag.get("set").and_then(|s| s.as_array()) {
+                for (i, item) in set.iter().enumerate() {
+                    out.push(normalize(func, g, i, item));
+                }
+            }
+        }
+        out
+    }
+}
+
+// A group bag is a map with a `set` array.
+fn is_group_bag(v: &Json) -> bool {
+    v.as_object()
+        .map(|o| object_get(o, "set").map(|s| s.is_array()).unwrap_or(false))
+        .unwrap_or(false)
+}
+
+// A function node has at least one child group bag (other than `name`).
+fn has_groups(v: &Json) -> bool {
+    match v.as_object() {
+        Some(o) => o.iter().any(|(k, val)| k.as_str() != "name" && is_group_bag(val)),
+        None => false,
+    }
+}
+
+fn has(raw: &Json, key: &str) -> bool {
+    raw.as_object()
+        .map(|o| object_get(o, key).is_some())
+        .unwrap_or(false)
+}
+
+fn normalize(func: &str, group: &str, index: usize, raw: &Json) -> Entry {
+    let id = raw
+        .get("id")
+        .filter(|v| !v.is_null())
+        .map(value_to_string_key);
+    let doc = raw.get("doc") == Some(&Json::Bool(true));
+    let client = raw
+        .get("client")
+        .filter(|v| !v.is_null())
+        .map(value_to_string_key);
+    Entry {
+        function: func.to_string(),
+        group: group.to_string(),
+        index,
+        id,
+        doc,
+        client,
+        input: resolve_input(raw),
+        expect: resolve_expect(raw),
+        raw: raw.clone(),
+    }
+}
+
+// String(x): the string itself if already a string, else its JSON text.
+fn value_to_string_key(v: &Json) -> String {
+    match v {
+        Json::Str(s) => s.clone(),
+        _ => v.to_string(),
+    }
+}
+
+fn resolve_input(raw: &Json) -> Input {
+    if has(raw, "ctx") {
+        return Input {
+            kind: InputKind::Ctx,
+            value: raw.get("ctx").cloned().unwrap_or(Json::Null),
+        };
+    }
+    if has(raw, "args") {
+        return Input {
+            kind: InputKind::Args,
+            value: raw.get("args").cloned().unwrap_or(Json::Null),
+        };
+    }
+    Input {
+        kind: InputKind::In,
+        value: if has(raw, "in") {
+            raw.get("in").cloned().unwrap_or(Json::Null)
+        } else {
+            Json::Null
+        },
+    }
+}
+
+fn parse_err(err: &Json) -> ErrorCheck {
+    if err == &Json::Bool(true) {
+        return ErrorCheck { any: true, text: None, regex: false };
+    }
+    if let Json::Str(s) = err {
+        if s.len() >= 2 && s.starts_with('/') && s.ends_with('/') {
+            let inner = &s[1..s.len() - 1];
+            if !inner.is_empty() {
+                return ErrorCheck {
+                    any: false,
+                    text: Some(inner.to_string()),
+                    regex: true,
+                };
+            }
+        }
+        return ErrorCheck {
+            any: false,
+            text: Some(s.clone()),
+            regex: false,
+        };
+    }
+    // Non-true, non-string err spec: treat as "any error".
+    ErrorCheck { any: true, text: None, regex: false }
+}
+
+fn resolve_expect(raw: &Json) -> Expect {
+    let match_part: Option<Json> = if has(raw, "match") {
+        Some(raw.get("match").cloned().unwrap_or(Json::Null))
+    } else {
+        None
+    };
+    if has(raw, "err") {
+        return Expect {
+            kind: ExpectKind::Error,
+            value: None,
+            error: Some(parse_err(raw.get("err").unwrap_or(&Json::Null))),
+            r#match: match_part,
+        };
+    }
+    if has(raw, "out") {
+        return Expect {
+            kind: ExpectKind::Value,
+            value: Some(raw.get("out").cloned().unwrap_or(Json::Null)),
+            error: None,
+            r#match: match_part,
+        };
+    }
+    if has(raw, "match") {
+        return Expect {
+            kind: ExpectKind::Match,
+            value: None,
+            error: None,
+            r#match: match_part,
+        };
+    }
+    Expect {
+        kind: ExpectKind::Absent,
+        value: None,
+        error: None,
+        r#match: None,
+    }
+}
+
+// ─── pure comparison helpers ───────────────────────────────────────────────
+
+// stringify(x) = x if it is already a string, else compact JSON.
+fn stringify(x: &Json) -> String {
+    match x {
+        Json::Str(s) => s.clone(),
+        _ => x.to_string(),
+    }
+}
+
+// Normalize "__NULL__" and Null -> Null deeply (both sides), mirroring the
+// runner's `flags.null` round-trip used by `equal`.
+fn norm_null(x: &Json) -> Json {
+    match x {
+        Json::Str(s) if s == NULLMARK => Json::Null,
+        Json::Null => Json::Null,
+        Json::Arr(a) => Json::Arr(a.iter().map(norm_null).collect()),
+        Json::Obj(o) => {
+            Json::Obj(o.iter().map(|(k, v)| (k.clone(), norm_null(v))).collect())
+        }
+        other => other.clone(),
+    }
+}
+
+// Normalize only "__NULL__" -> Null deeply, used by `equal_strict`.
+fn norm_mark(x: &Json) -> Json {
+    match x {
+        Json::Str(s) if s == NULLMARK => Json::Null,
+        Json::Arr(a) => Json::Arr(a.iter().map(norm_mark).collect()),
+        Json::Obj(o) => {
+            Json::Obj(o.iter().map(|(k, v)| (k.clone(), norm_mark(v))).collect())
+        }
+        other => other.clone(),
+    }
+}
+
+pub fn matchval(check: &Json, base: &Json) -> bool {
+    if check == base {
+        return true;
+    }
+    if let Json::Str(c) = check {
+        let basestr = stringify(base);
+        if c.len() >= 2 && c.starts_with('/') && c.ends_with('/') {
+            let inner = &c[1..c.len() - 1];
+            if !inner.is_empty() {
+                return mini_regex::is_match(inner, &basestr);
+            }
+        }
+        return basestr.to_lowercase().contains(&c.to_lowercase());
+    }
+    // (A "function" check is not representable as a JSON value.)
+    false
+}
+
+pub fn equal(expected: &Json, actual: &Json) -> bool {
+    deep_eq(&norm_null(expected), &norm_null(actual))
+}
+
+pub fn equal_strict(expected: &Json, actual: &Json) -> bool {
+    deep_eq(&norm_mark(expected), &norm_mark(actual))
+}
+
+fn deep_eq(a: &Json, b: &Json) -> bool {
+    match (a, b) {
+        (Json::Arr(av), Json::Arr(bv)) => {
+            av.len() == bv.len() && av.iter().zip(bv.iter()).all(|(x, y)| deep_eq(x, y))
+        }
+        (Json::Obj(ao), Json::Obj(bo)) => {
+            ao.len() == bo.len()
+                && ao.iter().all(|(k, v)| {
+                    object_get(bo, k).map(|bv| deep_eq(v, bv)).unwrap_or(false)
+                })
+        }
+        _ => a == b,
+    }
+}
+
+pub fn error_matches(check: &ErrorCheck, message: &str) -> bool {
+    if check.any {
+        return true;
+    }
+    let text = match &check.text {
+        Some(t) => t,
+        None => return false,
+    };
+    if check.regex {
+        return mini_regex::is_match(text, message);
+    }
+    message.to_lowercase().contains(&text.to_lowercase())
+}
+
+// Partial structural match: every leaf of `check` must match `base` at its path.
+pub fn struct_match(check: &Json, base: &Json) -> MatchResult {
+    let mut result = MatchResult {
+        ok: true,
+        path: Vec::new(),
+        expected: None,
+        actual: None,
+    };
+    let mut leaves: Vec<(Json, Vec<String>)> = Vec::new();
+    walk_leaves(check, &mut Vec::new(), &mut leaves);
+    for (val, path) in leaves {
+        if !result.ok {
+            break;
+        }
+        let baseval = getpath(base, &path);
+        // baseval == val
+        if let Some(bv) = &baseval {
+            if bv == &val {
+                continue;
+            }
+        }
+        // __UNDEF__ requires absent (missing / None)
+        if val == Json::Str(UNDEFMARK.to_string()) && is_absent(&baseval) {
+            continue;
+        }
+        // __EXISTS__ requires present (non-null)
+        if val == Json::Str(EXISTSMARK.to_string()) && is_present(&baseval) {
+            continue;
+        }
+        let bv_ref = baseval.clone().unwrap_or(Json::Null);
+        if !matchval(&val, &bv_ref) {
+            result = MatchResult {
+                ok: false,
+                path,
+                expected: Some(val),
+                actual: baseval,
+            };
+        }
+    }
+    result
+}
+
+// "absent" means the path resolved to nothing (None) or to a JSON null.
+fn is_absent(v: &Option<Json>) -> bool {
+    match v {
+        None => true,
+        Some(Json::Null) => true,
+        _ => false,
+    }
+}
+
+// "present" means a non-null value was found.
+fn is_present(v: &Option<Json>) -> bool {
+    matches!(v, Some(val) if !val.is_null())
+}
+
+fn is_node(v: &Json) -> bool {
+    matches!(v, Json::Arr(_) | Json::Obj(_))
+}
+
+fn walk_leaves(node: &Json, path: &mut Vec<String>, out: &mut Vec<(Json, Vec<String>)>) {
+    match node {
+        Json::Arr(a) => {
+            for (i, v) in a.iter().enumerate() {
+                path.push(i.to_string());
+                walk_leaves(v, path, out);
+                path.pop();
+            }
+        }
+        Json::Obj(o) => {
+            for (k, v) in o.iter() {
+                path.push(k.clone());
+                walk_leaves(v, path, out);
+                path.pop();
+            }
+        }
+        _ => {
+            out.push((node.clone(), path.clone()));
+        }
+    }
+    // (is_node guards: scalars fall through to the leaf branch.)
+    let _ = is_node;
+}
+
+// getpath returns None when the path runs off the end of the structure
+// (mirrors `undefined` in the TS reference).
+fn getpath(store: &Json, path: &[String]) -> Option<Json> {
+    let mut cur = store;
+    for key in path {
+        match cur {
+            Json::Null => return None,
+            Json::Arr(a) => {
+                let idx: usize = match key.parse() {
+                    Ok(i) => i,
+                    Err(_) => return None,
+                };
+                match a.get(idx) {
+                    Some(v) => cur = v,
+                    None => return None,
+                }
+            }
+            Json::Obj(o) => match object_get(o, key) {
+                Some(v) => cur = v,
+                None => return None,
+            },
+            _ => return None,
+        }
+    }
+    Some(cur.clone())
+}
+
+// Linear lookup over an insertion-ordered object (Vec of pairs).
+fn object_get<'a>(obj: &'a [(String, Json)], key: &str) -> Option<&'a Json> {
+    obj.iter().find(|(k, _)| k == key).map(|(_, v)| v)
+}
+
+// ─── minimal dependency-free JSON value + parser ───────────────────────────
+//
+// A small JSON value type and recursive-descent parser, sufficient for the
+// shared corpus. The object variant is a `Vec<(String, Json)>` so key insertion
+// order is preserved (matching serde_json's `preserve_order`), which is what
+// makes `functions()`/`groups()` return corpus order.
+mod json {
+    use std::fmt;
+    use std::fmt::Write as _;
+
+    #[derive(Debug, Clone)]
+    pub enum Json {
+        Null,
+        Bool(bool),
+        Num(f64),
+        Str(String),
+        Arr(Vec<Json>),
+        Obj(Vec<(String, Json)>),
+    }
+
+    impl Json {
+        pub fn is_null(&self) -> bool {
+            matches!(self, Json::Null)
+        }
+
+        pub fn is_array(&self) -> bool {
+            matches!(self, Json::Arr(_))
+        }
+
+        pub fn as_array(&self) -> Option<&Vec<Json>> {
+            match self {
+                Json::Arr(a) => Some(a),
+                _ => None,
+            }
+        }
+
+        pub fn as_object(&self) -> Option<&Vec<(String, Json)>> {
+            match self {
+                Json::Obj(o) => Some(o),
+                _ => None,
+            }
+        }
+
+        // Object field lookup; None for non-objects or missing keys.
+        pub fn get(&self, key: &str) -> Option<&Json> {
+            match self {
+                Json::Obj(o) => o.iter().find(|(k, _)| k == key).map(|(_, v)| v),
+                _ => None,
+            }
+        }
+    }
+
+    // Structural equality mirroring serde_json::Value's PartialEq: objects
+    // compare as key sets (order-independent), arrays element-wise, numbers by
+    // value. This matches how the helpers compared serde_json values before.
+    impl PartialEq for Json {
+        fn eq(&self, other: &Json) -> bool {
+            match (self, other) {
+                (Json::Null, Json::Null) => true,
+                (Json::Bool(a), Json::Bool(b)) => a == b,
+                (Json::Num(a), Json::Num(b)) => a == b,
+                (Json::Str(a), Json::Str(b)) => a == b,
+                (Json::Arr(a), Json::Arr(b)) => {
+                    a.len() == b.len() && a.iter().zip(b.iter()).all(|(x, y)| x == y)
+                }
+                (Json::Obj(a), Json::Obj(b)) => {
+                    a.len() == b.len()
+                        && a.iter().all(|(k, v)| {
+                            b.iter().find(|(bk, _)| bk == k).map(|(_, bv)| v == bv).unwrap_or(false)
+                        })
+                }
+                _ => false,
+            }
+        }
+    }
+
+    // Compact JSON serialization, matching serde_json's compact output for the
+    // value shapes in the corpus (no spaces; integers without a decimal point;
+    // shortest round-trip floats via Rust's f64 Display).
+    impl fmt::Display for Json {
+        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+            match self {
+                Json::Null => f.write_str("null"),
+                Json::Bool(true) => f.write_str("true"),
+                Json::Bool(false) => f.write_str("false"),
+                Json::Num(n) => write_num(*n, f),
+                Json::Str(s) => write_json_string(s, f),
+                Json::Arr(a) => {
+                    f.write_str("[")?;
+                    for (i, v) in a.iter().enumerate() {
+                        if i > 0 {
+                            f.write_str(",")?;
+                        }
+                        v.fmt(f)?;
+                    }
+                    f.write_str("]")
+                }
+                Json::Obj(o) => {
+                    f.write_str("{")?;
+                    for (i, (k, v)) in o.iter().enumerate() {
+                        if i > 0 {
+                            f.write_str(",")?;
+                        }
+                        write_json_string(k, f)?;
+                        f.write_str(":")?;
+                        v.fmt(f)?;
+                    }
+                    f.write_str("}")
+                }
+            }
+        }
+    }
+
+    fn write_num(n: f64, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        if !n.is_finite() {
+            // serde_json serializes non-finite numbers as null.
+            return f.write_str("null");
+        }
+        if n.fract() == 0.0 && n.abs() < 1e16 {
+            // Integer-valued: print without a decimal point (e.g. "42", "-3").
+            write!(f, "{}", n as i64)
+        } else {
+            // Shortest round-trip float (Rust's Display matches serde/ryu here).
+            write!(f, "{}", n)
+        }
+    }
+
+    fn write_json_string(s: &str, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("\"")?;
+        for c in s.chars() {
+            match c {
+                '"' => f.write_str("\\\"")?,
+                '\\' => f.write_str("\\\\")?,
+                '\n' => f.write_str("\\n")?,
+                '\r' => f.write_str("\\r")?,
+                '\t' => f.write_str("\\t")?,
+                '\u{08}' => f.write_str("\\b")?,
+                '\u{0C}' => f.write_str("\\f")?,
+                c if (c as u32) < 0x20 => write!(f, "\\u{:04x}", c as u32)?,
+                c => f.write_char(c)?,
+            }
+        }
+        f.write_str("\"")
+    }
+
+    pub fn parse(input: &str) -> Result<Json, String> {
+        let mut p = Parser {
+            chars: input.chars().collect(),
+            pos: 0,
+        };
+        p.skip_ws();
+        let v = p.parse_value()?;
+        p.skip_ws();
+        if p.pos != p.chars.len() {
+            return Err(format!("trailing characters at {}", p.pos));
+        }
+        Ok(v)
+    }
+
+    struct Parser {
+        chars: Vec<char>,
+        pos: usize,
+    }
+
+    impl Parser {
+        fn peek(&self) -> Option<char> {
+            self.chars.get(self.pos).copied()
+        }
+
+        fn bump(&mut self) -> Option<char> {
+            let c = self.chars.get(self.pos).copied();
+            if c.is_some() {
+                self.pos += 1;
+            }
+            c
+        }
+
+        fn skip_ws(&mut self) {
+            while let Some(c) = self.peek() {
+                if c == ' ' || c == '\t' || c == '\n' || c == '\r' {
+                    self.pos += 1;
+                } else {
+                    break;
+                }
+            }
+        }
+
+        fn parse_value(&mut self) -> Result<Json, String> {
+            self.skip_ws();
+            match self.peek() {
+                Some('{') => self.parse_object(),
+                Some('[') => self.parse_array(),
+                Some('"') => Ok(Json::Str(self.parse_string()?)),
+                Some('t') | Some('f') => self.parse_bool(),
+                Some('n') => self.parse_null(),
+                Some(c) if c == '-' || c.is_ascii_digit() => self.parse_number(),
+                Some(c) => Err(format!("unexpected character '{}' at {}", c, self.pos)),
+                None => Err("unexpected end of input".to_string()),
+            }
+        }
+
+        fn expect(&mut self, c: char) -> Result<(), String> {
+            match self.bump() {
+                Some(got) if got == c => Ok(()),
+                Some(got) => Err(format!("expected '{}' but found '{}' at {}", c, got, self.pos)),
+                None => Err(format!("expected '{}' but reached end of input", c)),
+            }
+        }
+
+        fn parse_object(&mut self) -> Result<Json, String> {
+            self.expect('{')?;
+            let mut obj: Vec<(String, Json)> = Vec::new();
+            self.skip_ws();
+            if self.peek() == Some('}') {
+                self.pos += 1;
+                return Ok(Json::Obj(obj));
+            }
+            loop {
+                self.skip_ws();
+                if self.peek() != Some('"') {
+                    return Err(format!("expected string key at {}", self.pos));
+                }
+                let key = self.parse_string()?;
+                self.skip_ws();
+                self.expect(':')?;
+                let val = self.parse_value()?;
+                obj.push((key, val));
+                self.skip_ws();
+                match self.bump() {
+                    Some(',') => continue,
+                    Some('}') => break,
+                    Some(c) => {
+                        return Err(format!("expected ',' or '}}' but found '{}' at {}", c, self.pos))
+                    }
+                    None => return Err("unterminated object".to_string()),
+                }
+            }
+            Ok(Json::Obj(obj))
+        }
+
+        fn parse_array(&mut self) -> Result<Json, String> {
+            self.expect('[')?;
+            let mut arr: Vec<Json> = Vec::new();
+            self.skip_ws();
+            if self.peek() == Some(']') {
+                self.pos += 1;
+                return Ok(Json::Arr(arr));
+            }
+            loop {
+                let val = self.parse_value()?;
+                arr.push(val);
+                self.skip_ws();
+                match self.bump() {
+                    Some(',') => continue,
+                    Some(']') => break,
+                    Some(c) => {
+                        return Err(format!("expected ',' or ']' but found '{}' at {}", c, self.pos))
+                    }
+                    None => return Err("unterminated array".to_string()),
+                }
+            }
+            Ok(Json::Arr(arr))
+        }
+
+        fn parse_bool(&mut self) -> Result<Json, String> {
+            if self.matches_keyword("true") {
+                Ok(Json::Bool(true))
+            } else if self.matches_keyword("false") {
+                Ok(Json::Bool(false))
+            } else {
+                Err(format!("invalid literal at {}", self.pos))
+            }
+        }
+
+        fn parse_null(&mut self) -> Result<Json, String> {
+            if self.matches_keyword("null") {
+                Ok(Json::Null)
+            } else {
+                Err(format!("invalid literal at {}", self.pos))
+            }
+        }
+
+        fn matches_keyword(&mut self, kw: &str) -> bool {
+            let end = self.pos + kw.len();
+            if end <= self.chars.len() && self.chars[self.pos..end].iter().collect::<String>() == kw
+            {
+                self.pos = end;
+                true
+            } else {
+                false
+            }
+        }
+
+        fn parse_number(&mut self) -> Result<Json, String> {
+            let start = self.pos;
+            if self.peek() == Some('-') {
+                self.pos += 1;
+            }
+            while let Some(c) = self.peek() {
+                if c.is_ascii_digit() {
+                    self.pos += 1;
+                } else {
+                    break;
+                }
+            }
+            if self.peek() == Some('.') {
+                self.pos += 1;
+                while let Some(c) = self.peek() {
+                    if c.is_ascii_digit() {
+                        self.pos += 1;
+                    } else {
+                        break;
+                    }
+                }
+            }
+            if matches!(self.peek(), Some('e') | Some('E')) {
+                self.pos += 1;
+                if matches!(self.peek(), Some('+') | Some('-')) {
+                    self.pos += 1;
+                }
+                while let Some(c) = self.peek() {
+                    if c.is_ascii_digit() {
+                        self.pos += 1;
+                    } else {
+                        break;
+                    }
+                }
+            }
+            let text: String = self.chars[start..self.pos].iter().collect();
+            text.parse::<f64>()
+                .map(Json::Num)
+                .map_err(|_| format!("invalid number '{}' at {}", text, start))
+        }
+
+        fn parse_string(&mut self) -> Result<String, String> {
+            self.expect('"')?;
+            let mut out = String::new();
+            loop {
+                match self.bump() {
+                    None => return Err("unterminated string".to_string()),
+                    Some('"') => break,
+                    Some('\\') => {
+                        let esc = self.bump().ok_or("unterminated escape")?;
+                        match esc {
+                            '"' => out.push('"'),
+                            '\\' => out.push('\\'),
+                            '/' => out.push('/'),
+                            'b' => out.push('\u{08}'),
+                            'f' => out.push('\u{0C}'),
+                            'n' => out.push('\n'),
+                            'r' => out.push('\r'),
+                            't' => out.push('\t'),
+                            'u' => {
+                                let cp = self.parse_hex4()?;
+                                if (0xD800..=0xDBFF).contains(&cp) {
+                                    // High surrogate: expect a following low surrogate.
+                                    if self.bump() != Some('\\') || self.bump() != Some('u') {
+                                        return Err("expected low surrogate".to_string());
+                                    }
+                                    let low = self.parse_hex4()?;
+                                    if !(0xDC00..=0xDFFF).contains(&low) {
+                                        return Err("invalid low surrogate".to_string());
+                                    }
+                                    let combined = 0x10000
+                                        + ((cp - 0xD800) << 10)
+                                        + (low - 0xDC00);
+                                    match char::from_u32(combined) {
+                                        Some(c) => out.push(c),
+                                        None => return Err("invalid surrogate pair".to_string()),
+                                    }
+                                } else if (0xDC00..=0xDFFF).contains(&cp) {
+                                    return Err("unexpected low surrogate".to_string());
+                                } else {
+                                    match char::from_u32(cp) {
+                                        Some(c) => out.push(c),
+                                        None => return Err("invalid code point".to_string()),
+                                    }
+                                }
+                            }
+                            other => {
+                                return Err(format!("invalid escape '\\{}'", other));
+                            }
+                        }
+                    }
+                    Some(c) => out.push(c),
+                }
+            }
+            Ok(out)
+        }
+
+        fn parse_hex4(&mut self) -> Result<u32, String> {
+            let mut v: u32 = 0;
+            for _ in 0..4 {
+                let c = self.bump().ok_or("unterminated \\u escape")?;
+                let d = c
+                    .to_digit(16)
+                    .ok_or_else(|| format!("invalid hex digit '{}'", c))?;
+                v = v * 16 + d;
+            }
+            Ok(v)
+        }
+    }
+}
+
+// ─── tiny dependency-free regex matcher ────────────────────────────────────
+//
+// PROTOTYPE: regex simplified. The workspace `rust/` crate ships its own regex
+// engine; to keep this prototype self-contained with no extra dependency, this
+// is a small backtracking matcher supporting a practical subset: literals, `.`,
+// `*`, `+`, `?`, `^`, `$`, character classes `[...]` (with ranges and `^`
+// negation) and the escapes `\d \w \s \D \W \S` plus escaped metacharacters.
+// `is_match` is unanchored (searches for the pattern anywhere) unless `^`/`$`
+// anchor it. This is sufficient for the corpus's err/match regexes.
+mod mini_regex {
+    #[derive(Clone)]
+    enum Atom {
+        Any,
+        Lit(char),
+        Class { negate: bool, items: Vec<ClassItem> },
+    }
+
+    #[derive(Clone)]
+    enum ClassItem {
+        Ch(char),
+        Range(char, char),
+        Digit,
+        NotDigit,
+        Word,
+        NotWord,
+        Space,
+        NotSpace,
+    }
+
+    struct Token {
+        atom: Atom,
+        // quantifier: (min, max) where max == usize::MAX means unbounded
+        min: usize,
+        max: usize,
+    }
+
+    fn class_item_matches(item: &ClassItem, c: char) -> bool {
+        match item {
+            ClassItem::Ch(x) => *x == c,
+            ClassItem::Range(a, b) => *a <= c && c <= *b,
+            ClassItem::Digit => c.is_ascii_digit(),
+            ClassItem::NotDigit => !c.is_ascii_digit(),
+            ClassItem::Word => c.is_alphanumeric() || c == '_',
+            ClassItem::NotWord => !(c.is_alphanumeric() || c == '_'),
+            ClassItem::Space => c.is_whitespace(),
+            ClassItem::NotSpace => !c.is_whitespace(),
+        }
+    }
+
+    fn atom_matches(atom: &Atom, c: char) -> bool {
+        match atom {
+            Atom::Any => c != '\n',
+            Atom::Lit(x) => *x == c,
+            Atom::Class { negate, items } => {
+                let any = items.iter().any(|it| class_item_matches(it, c));
+                if *negate {
+                    !any
+                } else {
+                    any
+                }
+            }
+        }
+    }
+
+    fn escape_to_item(c: char) -> Option<ClassItem> {
+        match c {
+            'd' => Some(ClassItem::Digit),
+            'D' => Some(ClassItem::NotDigit),
+            'w' => Some(ClassItem::Word),
+            'W' => Some(ClassItem::NotWord),
+            's' => Some(ClassItem::Space),
+            'S' => Some(ClassItem::NotSpace),
+            _ => None,
+        }
+    }
+
+    fn parse(pattern: &str) -> (Vec<Token>, bool, bool) {
+        let chars: Vec<char> = pattern.chars().collect();
+        let mut i = 0;
+        let mut anchored_start = false;
+        let mut anchored_end = false;
+        if i < chars.len() && chars[i] == '^' {
+            anchored_start = true;
+            i += 1;
+        }
+        let mut tokens: Vec<Token> = Vec::new();
+        while i < chars.len() {
+            let c = chars[i];
+            if c == '$' && i == chars.len() - 1 {
+                anchored_end = true;
+                break;
+            }
+            let atom = match c {
+                '.' => {
+                    i += 1;
+                    Atom::Any
+                }
+                '\\' => {
+                    i += 1;
+                    if i >= chars.len() {
+                        Atom::Lit('\\')
+                    } else {
+                        let e = chars[i];
+                        i += 1;
+                        if let Some(item) = escape_to_item(e) {
+                            Atom::Class { negate: false, items: vec![item] }
+                        } else {
+                            Atom::Lit(e)
+                        }
+                    }
+                }
+                '[' => {
+                    i += 1;
+                    let mut negate = false;
+                    if i < chars.len() && chars[i] == '^' {
+                        negate = true;
+                        i += 1;
+                    }
+                    let mut items: Vec<ClassItem> = Vec::new();
+                    while i < chars.len() && chars[i] != ']' {
+                        if chars[i] == '\\' && i + 1 < chars.len() {
+                            let e = chars[i + 1];
+                            i += 2;
+                            if let Some(item) = escape_to_item(e) {
+                                items.push(item);
+                            } else {
+                                items.push(ClassItem::Ch(e));
+                            }
+                            continue;
+                        }
+                        // range a-b
+                        if i + 2 < chars.len() && chars[i + 1] == '-' && chars[i + 2] != ']' {
+                            items.push(ClassItem::Range(chars[i], chars[i + 2]));
+                            i += 3;
+                            continue;
+                        }
+                        items.push(ClassItem::Ch(chars[i]));
+                        i += 1;
+                    }
+                    if i < chars.len() {
+                        i += 1; // consume ']'
+                    }
+                    Atom::Class { negate, items }
+                }
+                _ => {
+                    i += 1;
+                    Atom::Lit(c)
+                }
+            };
+            // quantifier
+            let (min, max) = if i < chars.len() {
+                match chars[i] {
+                    '*' => {
+                        i += 1;
+                        (0, usize::MAX)
+                    }
+                    '+' => {
+                        i += 1;
+                        (1, usize::MAX)
+                    }
+                    '?' => {
+                        i += 1;
+                        (0, 1)
+                    }
+                    _ => (1, 1),
+                }
+            } else {
+                (1, 1)
+            };
+            tokens.push(Token { atom, min, max });
+        }
+        (tokens, anchored_start, anchored_end)
+    }
+
+    // Try to match tokens[ti..] against text[pos..]; returns true if a full
+    // token match completes (respecting anchored_end).
+    fn try_match(
+        tokens: &[Token],
+        ti: usize,
+        text: &[char],
+        pos: usize,
+        anchored_end: bool,
+    ) -> bool {
+        if ti == tokens.len() {
+            return !anchored_end || pos == text.len();
+        }
+        let tok = &tokens[ti];
+        // Greedy: consume as many as possible (up to max), then backtrack.
+        let mut count = 0usize;
+        let mut positions: Vec<usize> = vec![pos];
+        let mut p = pos;
+        while count < tok.max && p < text.len() && atom_matches(&tok.atom, text[p]) {
+            p += 1;
+            count += 1;
+            positions.push(p);
+        }
+        // positions[k] = end position after matching k repetitions.
+        let mut k = count;
+        loop {
+            if k >= tok.min {
+                if try_match(tokens, ti + 1, text, positions[k], anchored_end) {
+                    return true;
+                }
+            }
+            if k == 0 {
+                break;
+            }
+            k -= 1;
+        }
+        false
+    }
+
+    pub fn is_match(pattern: &str, text: &str) -> bool {
+        let (tokens, anchored_start, anchored_end) = parse(pattern);
+        let chars: Vec<char> = text.chars().collect();
+        if anchored_start {
+            return try_match(&tokens, 0, &chars, 0, anchored_end);
+        }
+        // Unanchored: try every starting position.
+        for start in 0..=chars.len() {
+            if try_match(&tokens, 0, &chars, start, anchored_end) {
+                return true;
+            }
+        }
+        false
+    }
+}
diff --git a/test/proto/scala/Provider.scala b/test/proto/scala/Provider.scala
new file mode 100644
index 0000000..74a53e9
--- /dev/null
+++ b/test/proto/scala/Provider.scala
@@ -0,0 +1,600 @@
+// Test Provider (prototype) — Scala 3 port of the canonical ts/provider.ts.
+//
+// Reads the shared corpus (build/test/test.json) and hands test code clean,
+// normalized cases. It is NOT a test runner: it never calls the subject and
+// never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+//
+// Zero runtime dependencies (Scala/Java standard library only). There is no
+// JSON parser in the JVM stdlib, so a minimal one is bundled below — no
+// play-json / circe / jackson / gson.
+
+import scala.collection.mutable.ArrayBuffer
+import scala.util.matching.Regex
+import java.util.regex.Pattern
+
+// ─── JSON ADT ────────────────────────────────────────────────────────────────
+//
+// An order-preserving JSON model. JObj keeps its pairs as a Vector so that
+// iteration order (and "key presence" decisions) match the source document.
+
+sealed trait Json
+case object JNull extends Json
+final case class JBool(value: Boolean) extends Json
+final case class JNum(value: Double) extends Json
+final case class JStr(value: String) extends Json
+final case class JArr(items: Vector[Json]) extends Json
+final case class JObj(pairs: Vector[(String, Json)]) extends Json {
+  // First value for a key (mirrors LinkedHashMap.get / last-wins is avoided —
+  // a well-formed corpus has unique keys, so first == only).
+  def get(key: String): Option[Json] = pairs.collectFirst { case (k, v) if k == key => v }
+  def has(key: String): Boolean = pairs.exists(_._1 == key)
+  def keys: Vector[String] = pairs.map(_._1)
+}
+
+object Json {
+
+  // ─── parsing ───────────────────────────────────────────────────────────────
+
+  final class JsonException(msg: String) extends RuntimeException(msg)
+
+  def parse(text: String): Json = {
+    val p = new Parser(text)
+    p.skipWs()
+    val v = p.parseValue()
+    p.skipWs()
+    if (!p.atEnd) throw new JsonException(s"Trailing content at position ${p.pos}")
+    v
+  }
+
+  private final class Parser(val s: String) {
+    var pos: Int = 0
+    private val n: Int = s.length
+
+    def atEnd: Boolean = pos >= n
+
+    def skipWs(): Unit =
+      while (pos < n) {
+        val c = s.charAt(pos)
+        if (c == ' ' || c == '\t' || c == '\n' || c == '\r') pos += 1
+        else return
+      }
+
+    def peek(): Char = {
+      if (pos >= n) throw new JsonException("Unexpected end of input")
+      s.charAt(pos)
+    }
+
+    def parseValue(): Json = {
+      skipWs()
+      val c = peek()
+      c match {
+        case '{' => parseObject()
+        case '[' => parseArray()
+        case '"' => JStr(parseString())
+        case 't' | 'f' => parseBool()
+        case 'n' => parseNull()
+        case _ =>
+          if (c == '-' || (c >= '0' && c <= '9')) parseNumber()
+          else throw new JsonException(s"Unexpected char '$c' at position $pos")
+      }
+    }
+
+    def parseObject(): JObj = {
+      val buf = ArrayBuffer.empty[(String, Json)]
+      pos += 1 // consume '{'
+      skipWs()
+      if (peek() == '}') { pos += 1; return JObj(buf.toVector) }
+      var cont = true
+      while (cont) {
+        skipWs()
+        if (peek() != '"') throw new JsonException(s"Expected string key at position $pos")
+        val key = parseString()
+        skipWs()
+        if (peek() != ':') throw new JsonException(s"Expected ':' at position $pos")
+        pos += 1 // consume ':'
+        val v = parseValue()
+        buf.append(key -> v)
+        skipWs()
+        val ch = peek()
+        if (ch == ',') pos += 1
+        else if (ch == '}') { pos += 1; cont = false }
+        else throw new JsonException(s"Expected ',' or '}' at position $pos")
+      }
+      JObj(buf.toVector)
+    }
+
+    def parseArray(): JArr = {
+      val buf = ArrayBuffer.empty[Json]
+      pos += 1 // consume '['
+      skipWs()
+      if (peek() == ']') { pos += 1; return JArr(buf.toVector) }
+      var cont = true
+      while (cont) {
+        buf.append(parseValue())
+        skipWs()
+        val ch = peek()
+        if (ch == ',') pos += 1
+        else if (ch == ']') { pos += 1; cont = false }
+        else throw new JsonException(s"Expected ',' or ']' at position $pos")
+      }
+      JArr(buf.toVector)
+    }
+
+    def parseString(): String = {
+      pos += 1 // consume opening '"'
+      val b = new StringBuilder
+      var cont = true
+      while (cont) {
+        if (pos >= n) throw new JsonException("Unterminated string")
+        val c = s.charAt(pos); pos += 1
+        if (c == '"') cont = false
+        else if (c == '\\') {
+          if (pos >= n) throw new JsonException("Unterminated escape")
+          val e = s.charAt(pos); pos += 1
+          e match {
+            case '"'  => b.append('"')
+            case '\\' => b.append('\\')
+            case '/'  => b.append('/')
+            case 'b'  => b.append('\b')
+            case 'f'  => b.append('\f')
+            case 'n'  => b.append('\n')
+            case 'r'  => b.append('\r')
+            case 't'  => b.append('\t')
+            case 'u' =>
+              if (pos + 4 > n) throw new JsonException("Invalid \\u escape")
+              val hex = s.substring(pos, pos + 4); pos += 4
+              try b.append(Integer.parseInt(hex, 16).toChar)
+              catch { case _: NumberFormatException => throw new JsonException(s"Invalid \\u escape: $hex") }
+            case other => throw new JsonException(s"Invalid escape '\\$other'")
+          }
+        } else b.append(c)
+      }
+      b.toString
+    }
+
+    def parseBool(): Json = {
+      if (s.startsWith("true", pos)) { pos += 4; JBool(true) }
+      else if (s.startsWith("false", pos)) { pos += 5; JBool(false) }
+      else throw new JsonException(s"Invalid literal at position $pos")
+    }
+
+    def parseNull(): Json = {
+      if (s.startsWith("null", pos)) { pos += 4; JNull }
+      else throw new JsonException(s"Invalid literal at position $pos")
+    }
+
+    def parseNumber(): Json = {
+      val start = pos
+      if (peek() == '-') pos += 1
+      while (pos < n && Character.isDigit(s.charAt(pos))) pos += 1
+      if (pos < n && s.charAt(pos) == '.') {
+        pos += 1
+        while (pos < n && Character.isDigit(s.charAt(pos))) pos += 1
+      }
+      if (pos < n && (s.charAt(pos) == 'e' || s.charAt(pos) == 'E')) {
+        pos += 1
+        if (pos < n && (s.charAt(pos) == '+' || s.charAt(pos) == '-')) pos += 1
+        while (pos < n && Character.isDigit(s.charAt(pos))) pos += 1
+      }
+      val num = s.substring(start, pos)
+      try JNum(num.toDouble)
+      catch { case _: NumberFormatException => throw new JsonException(s"Invalid number '$num'") }
+    }
+  }
+
+  // ─── serialization ───────────────────────────────────────────────────────────
+
+  // Compact JSON serialization. Whole-number Doubles render without a trailing
+  // ".0" (so 42.0 -> "42"), matching the canonical stringify expectations.
+  def stringify(v: Json): String = {
+    val sb = new StringBuilder
+    write(v, sb)
+    sb.toString
+  }
+
+  private def write(v: Json, sb: StringBuilder): Unit = v match {
+    case JNull       => sb.append("null")
+    case JBool(b)    => sb.append(if (b) "true" else "false")
+    case JNum(d)     => writeNumber(d, sb)
+    case JStr(s)     => writeString(s, sb)
+    case JArr(items) =>
+      sb.append('[')
+      var first = true
+      items.foreach { x =>
+        if (!first) sb.append(',')
+        first = false
+        write(x, sb)
+      }
+      sb.append(']')
+    case JObj(pairs) =>
+      sb.append('{')
+      var first = true
+      pairs.foreach { case (k, x) =>
+        if (!first) sb.append(',')
+        first = false
+        writeString(k, sb)
+        sb.append(':')
+        write(x, sb)
+      }
+      sb.append('}')
+  }
+
+  private def writeNumber(d: Double, sb: StringBuilder): Unit =
+    if (d.isFinite && Math.floor(d) == d && Math.abs(d) < 1e15) sb.append(java.lang.Long.toString(d.toLong))
+    else sb.append(java.lang.Double.toString(d))
+
+  private def writeString(s: String, sb: StringBuilder): Unit = {
+    sb.append('"')
+    var i = 0
+    while (i < s.length) {
+      val c = s.charAt(i)
+      c match {
+        case '"'  => sb.append("\\\"")
+        case '\\' => sb.append("\\\\")
+        case '\b' => sb.append("\\b")
+        case '\f' => sb.append("\\f")
+        case '\n' => sb.append("\\n")
+        case '\r' => sb.append("\\r")
+        case '\t' => sb.append("\\t")
+        case _ =>
+          if (c < 0x20) sb.append("\\u%04x".format(c.toInt))
+          else sb.append(c)
+      }
+      i += 1
+    }
+    sb.append('"')
+  }
+}
+
+// ─── normalized records ────────────────────────────────────────────────────────
+
+enum InputKind { case In, Args, Ctx }
+enum ExpectKind { case Value, Error, Match, Absent }
+
+// Tagged input mirroring the runner's precedence (ctx -> args -> in). `value`
+// carries the relevant payload: the single `in` value (JNull if absent), the
+// `args` JArr, or the `ctx` JObj.
+final case class Input(kind: InputKind, value: Json)
+
+final case class ErrorCheck(any: Boolean, text: Option[String], regex: Boolean)
+
+// Tagged expectation. `value` is Some only for Value (presence-driven, may be
+// Some(JNull)). `match` is populated for Match and whenever a `match` block
+// co-exists with an err/out.
+final case class Expect(
+    kind: ExpectKind,
+    value: Option[Json],
+    error: Option[ErrorCheck],
+    `match`: Option[Json]
+)
+
+final case class Entry(
+    function: String,
+    group: String,
+    index: Int,
+    id: Option[String],
+    doc: Boolean,
+    client: Option[String],
+    input: Input,
+    expect: Expect,
+    raw: Json
+)
+
+// Result of a partial structural match: ok plus, on failure, the failing path
+// and the two compared values.
+final case class MatchResult(
+    ok: Boolean,
+    path: Seq[String] = Seq.empty,
+    expected: Option[Json] = None,
+    actual: Option[Json] = None
+)
+
+object TestProvider {
+
+  val NULLMARK = "__NULL__"
+  val UNDEFMARK = "__UNDEF__"
+  val EXISTSMARK = "__EXISTS__"
+
+  // Default corpus path resolves to build/test/test.json relative to the repo
+  // root. A provided path is used as-is, so callers (e.g. the smoke harness
+  // running from the repo root) may pass an absolute or repo-relative path.
+  def load(path: Option[String] = None): TestProvider = {
+    val file = path.getOrElse(defaultTestFile())
+    val text = new String(
+      java.nio.file.Files.readAllBytes(java.nio.file.Paths.get(file)),
+      java.nio.charset.StandardCharsets.UTF_8
+    )
+    new TestProvider(Json.parse(text))
+  }
+
+  private def defaultTestFile(): String = {
+    val here = java.nio.file.Paths.get(System.getProperty("user.dir"))
+    here.resolve(java.nio.file.Paths.get("build", "test", "test.json")).toString
+  }
+}
+
+final class TestProvider(val spec: Json) {
+
+  import TestProvider.*
+
+  def raw(): Json = spec
+
+  // The root map under which functions live: prefer spec.struct, else spec.
+  private def root(): JObj = spec match {
+    case o: JObj =>
+      o.get("struct") match {
+        case Some(s: JObj) => s
+        case _             => o
+      }
+    case _ => JObj(Vector.empty)
+  }
+
+  private def fnNode(fn: String): JObj = {
+    val node: Option[Json] = spec match {
+      case o: JObj =>
+        o.get("struct") match {
+          case Some(s: JObj) if s.has(fn) => s.get(fn)
+          case _ if o.has(fn)             => o.get(fn)
+          case _                          => None
+        }
+      case _ => None
+    }
+    node match {
+      case Some(m: JObj) => m
+      case _             => throw new IllegalArgumentException(s"Unknown function: $fn")
+    }
+  }
+
+  def functions(): Seq[String] =
+    root().pairs.collect { case (k, v) if isGroupBag(v) || hasGroups(v) => k }
+
+  def groups(fn: String): Seq[String] =
+    fnNode(fn).pairs.collect { case (k, v) if k != "name" && isGroupBag(v) => k }
+
+  // group == None means "all groups for the function".
+  def entries(fn: String, group: Option[String] = None): Seq[Entry] = {
+    val node = fnNode(fn)
+    val groupList = group match {
+      case Some(g) => Seq(g)
+      case None    => groups(fn)
+    }
+    val out = ArrayBuffer.empty[Entry]
+    for (g <- groupList) {
+      node.get(g) match {
+        case Some(bag: JObj) if isGroupBag(bag) =>
+          bag.get("set") match {
+            case Some(JArr(set)) =>
+              set.zipWithIndex.foreach { case (raw, i) => out.append(normalize(fn, g, i, raw)) }
+            case _ => ()
+          }
+        case _ => ()
+      }
+    }
+    out.toSeq
+  }
+
+  // A group bag is a map with a `set` array.
+  private def isGroupBag(v: Json): Boolean = v match {
+    case o: JObj =>
+      o.get("set") match {
+        case Some(_: JArr) => true
+        case _             => false
+      }
+    case _ => false
+  }
+
+  // A function node has at least one child group bag.
+  private def hasGroups(v: Json): Boolean = v match {
+    case o: JObj => o.pairs.exists { case (k, gv) => k != "name" && isGroupBag(gv) }
+    case _       => false
+  }
+
+  // ─── normalization ─────────────────────────────────────────────────────────
+
+  private def normalize(fn: String, group: String, index: Int, raw: Json): Entry = {
+    val o = raw match {
+      case m: JObj => m
+      case _       => JObj(Vector.empty)
+    }
+    Entry(
+      function = fn,
+      group = group,
+      index = index,
+      id = strOrNull(o.get("id")),
+      doc = o.get("doc").contains(JBool(true)),
+      client = strOrNull(o.get("client")),
+      input = resolveInput(o),
+      expect = resolveExpect(o),
+      raw = raw
+    )
+  }
+
+  // Mirror TS `null != x ? String(x) : null`: a present JSON null is treated as
+  // absent (None); other present values stringify (JStr stays as-is).
+  private def strOrNull(v: Option[Json]): Option[String] = v match {
+    case None | Some(JNull) => None
+    case Some(JStr(s))      => Some(s)
+    case Some(other)        => Some(Json.stringify(other))
+  }
+
+  private def resolveInput(raw: JObj): Input = {
+    if (raw.has("ctx")) Input(InputKind.Ctx, raw.get("ctx").get)
+    else if (raw.has("args")) Input(InputKind.Args, raw.get("args").get)
+    else Input(InputKind.In, if (raw.has("in")) raw.get("in").get else JNull)
+  }
+
+  private val reSlash = "^/(.+)/$".r
+
+  private def parseErr(err: Json): ErrorCheck = err match {
+    case JBool(true) => ErrorCheck(any = true, text = None, regex = false)
+    case JStr(s) =>
+      reSlash.findFirstMatchIn(s) match {
+        case Some(m) => ErrorCheck(any = false, text = Some(m.group(1)), regex = true)
+        case None    => ErrorCheck(any = false, text = Some(s), regex = false)
+      }
+    // Non-true, non-string err spec: treat as "any error".
+    case _ => ErrorCheck(any = true, text = None, regex = false)
+  }
+
+  private def resolveExpect(raw: JObj): Expect = {
+    val matchPart = if (raw.has("match")) raw.get("match") else None
+    if (raw.has("err"))
+      Expect(ExpectKind.Error, value = None, error = Some(parseErr(raw.get("err").get)), `match` = matchPart)
+    // KEY PRESENCE, not null-check: "out" present even if null => Value.
+    else if (raw.has("out"))
+      Expect(ExpectKind.Value, value = Some(raw.get("out").get), error = None, `match` = matchPart)
+    else if (raw.has("match"))
+      Expect(ExpectKind.Match, value = None, error = None, `match` = raw.get("match"))
+    else
+      Expect(ExpectKind.Absent, value = None, error = None, `match` = None)
+  }
+}
+
+// ─── pure comparison helpers ────────────────────────────────────────────────────
+//
+// Side-effect-free; the test calls them to assert. They reproduce the runner's
+// comparison logic so each port doesn't re-derive it. Semantics per PROVIDER.md §5.
+
+object TestMatch {
+
+  import TestProvider.{NULLMARK, UNDEFMARK, EXISTSMARK}
+
+  // Mirrors TS /^\/(.+)\/$/ — a "/re/" delimited regex literal.
+  private val reSlashMatch: Regex = "^/(.+)/$".r
+
+  // stringify(x) = x if it is already a string, else compact JSON.
+  def stringify(x: Json): String = x match {
+    case JStr(s) => s
+    case _       => Json.stringify(x)
+  }
+
+  // Normalize __NULL__ marks (and JNull) to JNull, recursively.
+  private def normNull(x: Json): Json = x match {
+    case JStr(NULLMARK) => JNull
+    case JNull          => JNull
+    case JArr(items)    => JArr(items.map(normNull))
+    case JObj(pairs)    => JObj(pairs.map { case (k, v) => k -> normNull(v) })
+    case _              => x
+  }
+
+  // Strict variant: only __NULL__ is normalized (JNull stays JNull anyway).
+  private def normMark(x: Json): Json = x match {
+    case JStr(NULLMARK) => JNull
+    case JArr(items)    => JArr(items.map(normMark))
+    case JObj(pairs)    => JObj(pairs.map { case (k, v) => k -> normMark(v) })
+    case _              => x
+  }
+
+  // matchval(check, base): check === base; else string check is "/re/" regex or
+  // case-insensitive substring on stringify(base). (Function checks aren't
+  // representable in parsed JSON.)
+  def matchval(check: Json, base: Json): Boolean = {
+    if (scalarEq(check, base)) true
+    else
+      check match {
+        case JStr(chk) =>
+          val basestr = stringify(base)
+          reSlashMatch.findFirstMatchIn(chk) match {
+            case Some(m) => Pattern.compile(m.group(1)).matcher(basestr).find()
+            case None    => basestr.toLowerCase.contains(chk.toLowerCase)
+          }
+        case _ => false
+      }
+  }
+
+  // equal: deep equality with __NULL__/JNull collapsed on both sides.
+  def equal(expected: Json, actual: Json): Boolean = deepEq(normNull(expected), normNull(actual))
+
+  // equalStrict: deep equality where absent (None at a path) is distinct from
+  // JNull; only __NULL__ is normalized.
+  def equalStrict(expected: Json, actual: Json): Boolean = deepEq(normMark(expected), normMark(actual))
+
+  // Scalar identity mirroring JS ===: numbers compared by value, JNull == JNull.
+  private def scalarEq(a: Json, b: Json): Boolean = (a, b) match {
+    case (JNull, JNull)         => true
+    case (JBool(x), JBool(y))   => x == y
+    case (JNum(x), JNum(y))     => x == y
+    case (JStr(x), JStr(y))     => x == y
+    case _                      => false
+  }
+
+  private def deepEq(a: Json, b: Json): Boolean = (a, b) match {
+    case (JArr(la), JArr(lb)) =>
+      la.length == lb.length && la.indices.forall(i => deepEq(la(i), lb(i)))
+    case (JArr(_), _) | (_, JArr(_)) => false
+    case (JObj(pa), JObj(pb)) =>
+      val mb = pb.toMap
+      pa.length == pb.length && pa.forall { case (k, v) => mb.get(k).exists(w => deepEq(v, w)) }
+    case (JObj(_), _) | (_, JObj(_)) => false
+    case _                           => scalarEq(a, b)
+  }
+
+  def errorMatches(check: ErrorCheck, message: String): Boolean = {
+    if (check.any) true
+    else
+      check.text match {
+        case None => false
+        case Some(t) =>
+          if (check.regex) Pattern.compile(t).matcher(message).find()
+          else message.toLowerCase.contains(t.toLowerCase)
+      }
+  }
+
+  // Partial structural match: every leaf of `check` must match `base` at its path.
+  def structMatch(check: Json, base: Json): MatchResult = {
+    var result = MatchResult(ok = true)
+    walkLeaves(
+      check,
+      Vector.empty,
+      (value, path) => {
+        if (result.ok) {
+          val baseval: Option[Json] = getpath(base, path) // None == absent
+          value match {
+            case _ if baseval.exists(bv => scalarEq(value, bv)) => () // equal
+            case JStr(UNDEFMARK) if baseval.isEmpty             => () // require absent
+            case JStr(EXISTSMARK) if baseval.exists(_ != JNull) => () // require present & non-null
+            case _ =>
+              val compareBase = baseval.getOrElse(JNull)
+              if (!matchval(value, compareBase))
+                result = MatchResult(ok = false, path = path, expected = Some(value), actual = baseval)
+          }
+        }
+      }
+    )
+    result
+  }
+
+  private def walkLeaves(node: Json, path: Vector[String], fn: (Json, Vector[String]) => Unit): Unit =
+    node match {
+      case JArr(items) =>
+        items.zipWithIndex.foreach { case (v, i) => walkLeaves(v, path :+ i.toString, fn) }
+      case JObj(pairs) =>
+        pairs.foreach { case (k, v) => walkLeaves(v, path :+ k, fn) }
+      case leaf => fn(leaf, path)
+    }
+
+  // Returns None for an absent path (distinct from a present JNull).
+  private def getpath(store: Json, path: Vector[String]): Option[Json] = {
+    var cur: Json = store
+    var i = 0
+    var missing = false
+    while (i < path.length && !missing) {
+      val key = path(i)
+      cur match {
+        case JArr(items) =>
+          key.toIntOption match {
+            case Some(idx) if idx >= 0 && idx < items.length => cur = items(idx)
+            case _                                           => missing = true
+          }
+        case o: JObj =>
+          o.get(key) match {
+            case Some(v) => cur = v
+            case None    => missing = true
+          }
+        case _ => missing = true
+      }
+      i += 1
+    }
+    if (missing) None else Some(cur)
+  }
+}
diff --git a/test/proto/scala/Smoke.scala b/test/proto/scala/Smoke.scala
new file mode 100644
index 0000000..fdba8df
--- /dev/null
+++ b/test/proto/scala/Smoke.scala
@@ -0,0 +1,48 @@
+// Smoke test for the Scala test provider port. Prints summary stats that must
+// match the canonical TS output documented in PROVIDER.md.
+//
+// Run from the repo root (Scala 3 toolchain required):
+//   cd test/proto/scala && scalac Provider.scala Smoke.scala -d out \
+//     && (cd /home/user/struct && scala -cp test/proto/scala/out Smoke)
+
+import scala.collection.immutable.TreeMap
+
+object Smoke {
+
+  def main(args: Array[String]): Unit = {
+    val path = if (args.length > 0) Some(args(0)) else Some("build/test/test.json")
+    val prov = TestProvider.load(path)
+
+    val fns = prov.functions()
+    println("functions: " + fns.mkString(", "))
+
+    var total = 0
+    var expectKinds = TreeMap.empty[String, Int]
+    var inputKinds = TreeMap.empty[String, Int]
+    for (fn <- fns) {
+      for (e <- prov.entries(fn)) {
+        total += 1
+        val ek = e.expect.kind.toString.toLowerCase
+        val ik = e.input.kind.toString.toLowerCase
+        expectKinds = expectKinds.updated(ek, expectKinds.getOrElse(ek, 0) + 1)
+        inputKinds = inputKinds.updated(ik, inputKinds.getOrElse(ik, 0) + 1)
+      }
+    }
+
+    println("total entries: " + total)
+    println("expect kinds: " + joinCounts(expectKinds))
+    println("input kinds: " + joinCounts(inputKinds))
+
+    val e = prov.entries("getpath", Some("basic")).head
+    println(
+      "getpath/basic[0]: id=" + e.id.orNull +
+        ", doc=" + e.doc +
+        ", input.kind=" + e.input.kind.toString.toLowerCase +
+        ", expect.kind=" + e.expect.kind.toString.toLowerCase +
+        ", expect.value=" + e.expect.value.map(TestMatch.stringify).orNull
+    )
+  }
+
+  private def joinCounts(counts: TreeMap[String, Int]): String =
+    counts.map { case (k, v) => s"$k=$v" }.mkString(", ")
+}
diff --git a/test/proto/swift/Provider.swift b/test/proto/swift/Provider.swift
new file mode 100644
index 0000000..900585a
--- /dev/null
+++ b/test/proto/swift/Provider.swift
@@ -0,0 +1,799 @@
+// Test Provider (prototype) — Swift port of the canonical ts/provider.ts.
+//
+// Reads the shared corpus (build/test/test.json) and hands test code clean,
+// normalized cases. It is NOT a test runner: it never calls the subject and
+// never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+//
+// Dependency-free: Foundation (stdlib) only, no SwiftPM third-party deps.
+//
+// IMPORTANT: Foundation's JSONSerialization yields NSDictionary, which does
+// not preserve key order. functions()/groups() must return corpus order
+// (minor first), so this file ships a small order-preserving JSON parser that
+// yields a JSON enum with ordered object pairs.
+
+import Foundation
+
+private let NULLMARK = "__NULL__"
+private let UNDEFMARK = "__UNDEF__"
+private let EXISTSMARK = "__EXISTS__"
+
+// ─── order-preserving JSON value ───────────────────────────────────────────
+
+/// An order-preserving JSON value. Object pairs keep their source order so
+/// functions()/groups() can return corpus order.
+public enum JSON {
+  case null
+  case bool(Bool)
+  case num(Double)
+  case str(String)
+  case arr([JSON])
+  case obj([(String, JSON)])
+}
+
+extension JSON {
+  /// Whether this is an object (map) node.
+  public var isObject: Bool {
+    if case .obj = self { return true }
+    return false
+  }
+
+  /// Whether this is an array (list) node.
+  public var isArray: Bool {
+    if case .arr = self { return true }
+    return false
+  }
+
+  /// The ordered object pairs, or nil if not an object.
+  public var pairs: [(String, JSON)]? {
+    if case .obj(let p) = self { return p }
+    return nil
+  }
+
+  /// The array items, or nil if not an array.
+  public var items: [JSON]? {
+    if case .arr(let a) = self { return a }
+    return nil
+  }
+
+  /// Whether the (object) node contains `key` — KEY PRESENCE, not null-check.
+  public func has(_ key: String) -> Bool {
+    if case .obj(let p) = self {
+      for (k, _) in p where k == key { return true }
+    }
+    return false
+  }
+
+  /// Value for `key` in an object node, by key presence. Returns nil if the
+  /// key is absent. A present key whose value is JSON null returns `.null`.
+  public func get(_ key: String) -> JSON? {
+    if case .obj(let p) = self {
+      for (k, v) in p where k == key { return v }
+    }
+    return nil
+  }
+
+  /// String value if `.str`, else nil.
+  public var asString: String? {
+    if case .str(let s) = self { return s }
+    return nil
+  }
+
+  /// The ordered keys of an object node (empty for non-objects).
+  public var keys: [String] {
+    if case .obj(let p) = self { return p.map { $0.0 } }
+    return []
+  }
+
+  /// Compact JSON serialization with stable (source) object order.
+  public func compact() -> String {
+    switch self {
+    case .null:
+      return "null"
+    case .bool(let b):
+      return b ? "true" : "false"
+    case .num(let n):
+      return JSON.numString(n)
+    case .str(let s):
+      return JSON.encodeString(s)
+    case .arr(let a):
+      return "[" + a.map { $0.compact() }.joined(separator: ",") + "]"
+    case .obj(let p):
+      return "{"
+        + p.map { JSON.encodeString($0.0) + ":" + $0.1.compact() }.joined(separator: ",")
+        + "}"
+    }
+  }
+
+  // Render a Double the way JSON expects: integral values without a trailing
+  // ".0", non-integral values via Swift's shortest round-trippable form.
+  static func numString(_ n: Double) -> String {
+    if n == n.rounded() && abs(n) < 1e15 && n.isFinite {
+      return String(Int64(n))
+    }
+    return String(n)
+  }
+
+  static func encodeString(_ s: String) -> String {
+    var out = "\""
+    for ch in s.unicodeScalars {
+      switch ch {
+      case "\"": out += "\\\""
+      case "\\": out += "\\\\"
+      case "\n": out += "\\n"
+      case "\r": out += "\\r"
+      case "\t": out += "\\t"
+      case "\u{08}": out += "\\b"
+      case "\u{0C}": out += "\\f"
+      default:
+        if ch.value < 0x20 {
+          out += String(format: "\\u%04x", ch.value)
+        } else {
+          out.unicodeScalars.append(ch)
+        }
+      }
+    }
+    out += "\""
+    return out
+  }
+}
+
+// ─── hand-rolled, order-preserving JSON parser ─────────────────────────────
+
+public enum JSONParseError: Error, CustomStringConvertible {
+  case unexpected(String, Int)
+
+  public var description: String {
+    switch self {
+    case .unexpected(let msg, let pos): return "JSON parse error at \(pos): \(msg)"
+    }
+  }
+}
+
+public enum JSONParser {
+  public static func parse(_ text: String) throws -> JSON {
+    var p = Cursor(Array(text.unicodeScalars))
+    p.skipWhitespace()
+    let value = try p.parseValue()
+    p.skipWhitespace()
+    if !p.atEnd {
+      throw JSONParseError.unexpected("trailing content", p.pos)
+    }
+    return value
+  }
+
+  struct Cursor {
+    let s: [Unicode.Scalar]
+    var pos: Int = 0
+
+    init(_ s: [Unicode.Scalar]) { self.s = s }
+
+    var atEnd: Bool { pos >= s.count }
+
+    func peek() -> Unicode.Scalar? { pos < s.count ? s[pos] : nil }
+
+    mutating func next() -> Unicode.Scalar? {
+      guard pos < s.count else { return nil }
+      defer { pos += 1 }
+      return s[pos]
+    }
+
+    mutating func skipWhitespace() {
+      while pos < s.count {
+        let c = s[pos]
+        if c == " " || c == "\t" || c == "\n" || c == "\r" {
+          pos += 1
+        } else {
+          break
+        }
+      }
+    }
+
+    mutating func parseValue() throws -> JSON {
+      skipWhitespace()
+      guard let c = peek() else {
+        throw JSONParseError.unexpected("unexpected end of input", pos)
+      }
+      switch c {
+      case "{": return try parseObject()
+      case "[": return try parseArray()
+      case "\"": return .str(try parseString())
+      case "t", "f": return try parseBool()
+      case "n": return try parseNull()
+      default: return try parseNumber()
+      }
+    }
+
+    mutating func parseObject() throws -> JSON {
+      pos += 1  // consume '{'
+      var pairs: [(String, JSON)] = []
+      skipWhitespace()
+      if peek() == "}" {
+        pos += 1
+        return .obj(pairs)
+      }
+      while true {
+        skipWhitespace()
+        guard peek() == "\"" else {
+          throw JSONParseError.unexpected("expected object key string", pos)
+        }
+        let key = try parseString()
+        skipWhitespace()
+        guard next() == ":" else {
+          throw JSONParseError.unexpected("expected ':' after object key", pos)
+        }
+        let value = try parseValue()
+        pairs.append((key, value))
+        skipWhitespace()
+        let sep = next()
+        if sep == "," { continue }
+        if sep == "}" { break }
+        throw JSONParseError.unexpected("expected ',' or '}' in object", pos)
+      }
+      return .obj(pairs)
+    }
+
+    mutating func parseArray() throws -> JSON {
+      pos += 1  // consume '['
+      var items: [JSON] = []
+      skipWhitespace()
+      if peek() == "]" {
+        pos += 1
+        return .arr(items)
+      }
+      while true {
+        let value = try parseValue()
+        items.append(value)
+        skipWhitespace()
+        let sep = next()
+        if sep == "," { continue }
+        if sep == "]" { break }
+        throw JSONParseError.unexpected("expected ',' or ']' in array", pos)
+      }
+      return .arr(items)
+    }
+
+    mutating func parseString() throws -> String {
+      pos += 1  // consume opening quote
+      var out = String.UnicodeScalarView()
+      while let c = next() {
+        if c == "\"" {
+          return String(out)
+        }
+        if c == "\\" {
+          guard let e = next() else {
+            throw JSONParseError.unexpected("unterminated escape", pos)
+          }
+          switch e {
+          case "\"": out.append("\"")
+          case "\\": out.append("\\")
+          case "/": out.append("/")
+          case "n": out.append("\n")
+          case "t": out.append("\t")
+          case "r": out.append("\r")
+          case "b": out.append("\u{08}")
+          case "f": out.append("\u{0C}")
+          case "u":
+            let scalar = try parseUnicodeEscape()
+            out.append(scalar)
+          default:
+            throw JSONParseError.unexpected("invalid escape \\\(e)", pos)
+          }
+        } else {
+          out.append(c)
+        }
+      }
+      throw JSONParseError.unexpected("unterminated string", pos)
+    }
+
+    mutating func parseUnicodeEscape() throws -> Unicode.Scalar {
+      let high = try hex4()
+      // Surrogate pair handling.
+      if high >= 0xD800 && high <= 0xDBFF {
+        if peek() == "\\" {
+          pos += 1
+          guard next() == "u" else {
+            throw JSONParseError.unexpected("expected low surrogate", pos)
+          }
+          let low = try hex4()
+          if low >= 0xDC00 && low <= 0xDFFF {
+            let combined = 0x10000 + ((high - 0xD800) << 10) + (low - 0xDC00)
+            guard let scalar = Unicode.Scalar(combined) else {
+              throw JSONParseError.unexpected("invalid surrogate pair", pos)
+            }
+            return scalar
+          }
+          throw JSONParseError.unexpected("invalid low surrogate", pos)
+        }
+        throw JSONParseError.unexpected("unpaired high surrogate", pos)
+      }
+      guard let scalar = Unicode.Scalar(high) else {
+        throw JSONParseError.unexpected("invalid unicode scalar", pos)
+      }
+      return scalar
+    }
+
+    mutating func hex4() throws -> Int {
+      var value = 0
+      for _ in 0..<4 {
+        guard let c = next(), let d = hexDigit(c) else {
+          throw JSONParseError.unexpected("invalid \\u escape", pos)
+        }
+        value = value * 16 + d
+      }
+      return value
+    }
+
+    func hexDigit(_ c: Unicode.Scalar) -> Int? {
+      switch c {
+      case "0"..."9": return Int(c.value - 48)
+      case "a"..."f": return Int(c.value - 87)
+      case "A"..."F": return Int(c.value - 55)
+      default: return nil
+      }
+    }
+
+    mutating func parseBool() throws -> JSON {
+      if match("true") { return .bool(true) }
+      if match("false") { return .bool(false) }
+      throw JSONParseError.unexpected("invalid literal", pos)
+    }
+
+    mutating func parseNull() throws -> JSON {
+      if match("null") { return .null }
+      throw JSONParseError.unexpected("invalid literal", pos)
+    }
+
+    mutating func match(_ literal: String) -> Bool {
+      let lit = Array(literal.unicodeScalars)
+      guard pos + lit.count <= s.count else { return false }
+      for (i, ch) in lit.enumerated() where s[pos + i] != ch { return false }
+      pos += lit.count
+      return true
+    }
+
+    mutating func parseNumber() throws -> JSON {
+      let start = pos
+      if peek() == "-" { pos += 1 }
+      while let c = peek(), isNumberChar(c) { pos += 1 }
+      let scalars = s[start..<pos]
+      let str = String(String.UnicodeScalarView(scalars))
+      guard let value = Double(str), !str.isEmpty else {
+        throw JSONParseError.unexpected("invalid number '\(str)'", start)
+      }
+      return .num(value)
+    }
+
+    func isNumberChar(_ c: Unicode.Scalar) -> Bool {
+      switch c {
+      case "0"..."9", ".", "e", "E", "+", "-": return true
+      default: return false
+      }
+    }
+  }
+}
+
+// ─── tagged Input / Expect / Entry ─────────────────────────────────────────
+
+public enum InputKind: String {
+  case `in`
+  case args
+  case ctx
+}
+
+public enum ExpectKind: String {
+  case value
+  case error
+  case match
+  case absent
+}
+
+public struct Input {
+  public let kind: InputKind
+  /// The single argument (kind .in; absent "in" key => .null), the positional
+  /// argument vector (kind .args), or the context map (kind .ctx).
+  public let value: JSON
+}
+
+public struct ErrorCheck {
+  public let any: Bool
+  public let text: String?
+  public let regex: Bool
+}
+
+public struct Expect {
+  public let kind: ExpectKind
+  /// Present for kind .value (may be literal JSON null).
+  public let value: JSON?
+  /// Present for kind .error.
+  public let error: ErrorCheck?
+  /// Set whenever a "match" key co-exists (also the payload for kind .match).
+  public let match: JSON?
+}
+
+public struct Entry {
+  public let function: String
+  public let group: String
+  public let index: Int
+  public let id: String?
+  public let doc: Bool
+  public let client: String?
+  public let input: Input
+  public let expect: Expect
+  public let raw: JSON
+}
+
+public struct MatchResult {
+  public let ok: Bool
+  public let path: [String]?
+  public let expected: JSON?
+  public let actual: JSON?
+
+  public init(ok: Bool, path: [String]? = nil, expected: JSON? = nil, actual: JSON? = nil) {
+    self.ok = ok
+    self.path = path
+    self.expected = expected
+    self.actual = actual
+  }
+}
+
+// ─── the provider ──────────────────────────────────────────────────────────
+
+public final class TestProvider {
+  public let spec: JSON
+
+  public init(_ spec: JSON) {
+    self.spec = spec
+  }
+
+  /// Load and parse the corpus. Default resolves to build/test/test.json
+  /// relative to this source file (test/proto/swift -> repo root).
+  public static func load(_ path: String? = nil) -> TestProvider {
+    let file = path ?? defaultTestFile()
+    guard let text = try? String(contentsOfFile: file, encoding: .utf8) else {
+      fatalError("Failed to read corpus at \(file)")
+    }
+    do {
+      let spec = try JSONParser.parse(text)
+      return TestProvider(spec)
+    } catch {
+      fatalError("Failed to parse corpus at \(file): \(error)")
+    }
+  }
+
+  private static func defaultTestFile() -> String {
+    // #filePath = test/proto/swift/Provider.swift
+    let here = URL(fileURLWithPath: #filePath)
+      .deletingLastPathComponent()  // swift/
+      .deletingLastPathComponent()  // proto/
+      .deletingLastPathComponent()  // test/
+      .deletingLastPathComponent()  // struct/ (repo root)
+      .appendingPathComponent("build")
+      .appendingPathComponent("test")
+      .appendingPathComponent("test.json")
+    return here.path
+  }
+
+  /// The parsed test.json (escape hatch).
+  public func raw() -> JSON {
+    return spec
+  }
+
+  private func root() -> JSON {
+    if let structNode = spec.get("struct") {
+      return structNode
+    }
+    return spec
+  }
+
+  private func fnNode(_ fn: String) -> JSON {
+    if let node = spec.get("struct")?.get(fn) {
+      return node
+    }
+    if let node = spec.get(fn) {
+      return node
+    }
+    fatalError("Unknown function: \(fn)")
+  }
+
+  /// The function names in corpus order (minor first).
+  public func functions() -> [String] {
+    let r = root()
+    return r.keys.filter { k in
+      let v = r.get(k)!
+      return isGroupBag(v) || hasGroups(v)
+    }
+  }
+
+  /// The group names for `fn` in corpus order.
+  public func groups(_ fn: String) -> [String] {
+    let node = fnNode(fn)
+    return node.keys.filter { k in
+      k != "name" && isGroupBag(node.get(k)!)
+    }
+  }
+
+  /// All entries across `fn`'s groups, or one group's entries.
+  public func entries(_ fn: String, group: String? = nil) -> [Entry] {
+    let node = fnNode(fn)
+    let groupNames = group != nil ? [group!] : groups(fn)
+    var out: [Entry] = []
+    for g in groupNames {
+      guard let bag = node.get(g), isGroupBag(bag) else { continue }
+      guard let set = bag.get("set")?.items else { continue }
+      for (i, rawEntry) in set.enumerated() {
+        out.append(normalize(fn, g, i, rawEntry))
+      }
+    }
+    return out
+  }
+}
+
+// A group bag is an object with a `set` array.
+private func isGroupBag(_ v: JSON) -> Bool {
+  guard v.isObject else { return false }
+  return v.get("set")?.isArray == true
+}
+
+// A function node has at least one child group bag.
+private func hasGroups(_ v: JSON) -> Bool {
+  guard case .obj(let pairs) = v else { return false }
+  for (k, child) in pairs where k != "name" && isGroupBag(child) { return true }
+  return false
+}
+
+private func normalize(_ fn: String, _ group: String, _ index: Int, _ raw: JSON) -> Entry {
+  return Entry(
+    function: fn,
+    group: group,
+    index: index,
+    id: stringField(raw, "id"),
+    doc: raw.get("doc").map { isTrue($0) } ?? false,
+    client: stringField(raw, "client"),
+    input: resolveInput(raw),
+    expect: resolveExpect(raw),
+    raw: raw
+  )
+}
+
+private func isTrue(_ v: JSON) -> Bool {
+  if case .bool(true) = v { return true }
+  return false
+}
+
+// Mirror `null != raw.<key>` then String(...): present-and-not-null => string.
+private func stringField(_ raw: JSON, _ key: String) -> String? {
+  guard let v = raw.get(key) else { return nil }
+  switch v {
+  case .null: return nil
+  case .str(let s): return s
+  case .bool(let b): return b ? "true" : "false"
+  case .num(let n): return JSON.numString(n)
+  default: return v.compact()
+  }
+}
+
+private func resolveInput(_ raw: JSON) -> Input {
+  if raw.has("ctx") {
+    return Input(kind: .ctx, value: raw.get("ctx")!)
+  }
+  if raw.has("args") {
+    return Input(kind: .args, value: raw.get("args")!)
+  }
+  // kind .in, with the single argument; absent "in" key => native null.
+  return Input(kind: .in, value: raw.has("in") ? raw.get("in")! : .null)
+}
+
+private func parseErr(_ err: JSON) -> ErrorCheck {
+  if case .bool(true) = err {
+    return ErrorCheck(any: true, text: nil, regex: false)
+  }
+  if case .str(let s) = err {
+    if let inner = regexInner(s) {
+      return ErrorCheck(any: false, text: inner, regex: true)
+    }
+    return ErrorCheck(any: false, text: s, regex: false)
+  }
+  // Non-true, non-string err spec: treat as "any error".
+  return ErrorCheck(any: true, text: nil, regex: false)
+}
+
+// "/re/" => "re"; otherwise nil. Mirrors /^\/(.+)\/$/.
+private func regexInner(_ s: String) -> String? {
+  guard s.count >= 3, s.hasPrefix("/"), s.hasSuffix("/") else { return nil }
+  let inner = String(s.dropFirst().dropLast())
+  return inner.isEmpty ? nil : inner
+}
+
+private func resolveExpect(_ raw: JSON) -> Expect {
+  // Attach match whenever a "match" key exists (key presence).
+  let matchPart: JSON? = raw.has("match") ? raw.get("match")! : nil
+  if raw.has("err") {
+    return Expect(
+      kind: .error, value: nil, error: parseErr(raw.get("err")!), match: matchPart)
+  }
+  // "out" present even if JSON null => value (KEY PRESENCE, not null-check).
+  if raw.has("out") {
+    return Expect(kind: .value, value: raw.get("out")!, error: nil, match: matchPart)
+  }
+  if raw.has("match") {
+    return Expect(kind: .match, value: nil, error: nil, match: raw.get("match")!)
+  }
+  return Expect(kind: .absent, value: nil, error: nil, match: nil)
+}
+
+// ─── pure comparison helpers ───────────────────────────────────────────────
+
+/// `x` if already a string, else compact JSON.
+public func stringify(_ x: JSON) -> String {
+  if case .str(let s) = x { return s }
+  return x.compact()
+}
+
+private func normNull(_ x: JSON) -> JSON {
+  switch x {
+  case .str(let s) where s == NULLMARK:
+    return .null
+  case .arr(let a):
+    return .arr(a.map { normNull($0) })
+  case .obj(let p):
+    return .obj(p.map { ($0.0, normNull($0.1)) })
+  default:
+    return x
+  }
+}
+
+private func normMark(_ x: JSON) -> JSON {
+  // Only __NULL__ is normalized; absent stays distinct from null.
+  switch x {
+  case .str(let s) where s == NULLMARK:
+    return .null
+  case .arr(let a):
+    return .arr(a.map { normMark($0) })
+  case .obj(let p):
+    return .obj(p.map { ($0.0, normMark($0.1)) })
+  default:
+    return x
+  }
+}
+
+/// Scalar primitive match. `check == base`; else if `check` is a string:
+/// "/re/" => regex test; otherwise case-insensitive substring containment.
+public func matchval(_ check: JSON, _ base: JSON) -> Bool {
+  if jsonEqual(check, base) {
+    return true
+  }
+  if case .str(let cs) = check {
+    let basestr = stringify(base)
+    if let inner = regexInner(cs) {
+      return regexTest(inner, basestr)
+    }
+    return basestr.lowercased().contains(cs.lowercased())
+  }
+  return false
+}
+
+/// Deep equality with null/undefined collapsed (runner default null:true).
+public func equal(_ expected: JSON, _ actual: JSON) -> Bool {
+  return deepEq(normNull(expected), normNull(actual))
+}
+
+/// Strict deep equality: __NULL__ is normalized but absent (here .null carries
+/// JSON null only) stays distinct (runner null:false functions).
+public func equalStrict(_ expected: JSON, _ actual: JSON) -> Bool {
+  return deepEq(normMark(expected), normMark(actual))
+}
+
+// Raw structural equality on JSON values (no NULLMARK normalization).
+private func jsonEqual(_ a: JSON, _ b: JSON) -> Bool {
+  switch (a, b) {
+  case (.null, .null): return true
+  case (.bool(let x), .bool(let y)): return x == y
+  case (.num(let x), .num(let y)): return x == y
+  case (.str(let x), .str(let y)): return x == y
+  case (.arr(let x), .arr(let y)):
+    return x.count == y.count && zip(x, y).allSatisfy { jsonEqual($0.0, $0.1) }
+  case (.obj(let x), .obj(let y)):
+    guard x.count == y.count else { return false }
+    let bm = Dictionary(y.map { ($0.0, $0.1) }, uniquingKeysWith: { a, _ in a })
+    for (k, v) in x {
+      guard let bv = bm[k], jsonEqual(v, bv) else { return false }
+    }
+    return true
+  default:
+    return false
+  }
+}
+
+private func deepEq(_ a: JSON, _ b: JSON) -> Bool {
+  return jsonEqual(a, b)
+}
+
+/// ErrorCheck vs a thrown message. `any` => true; `regex` => regex test;
+/// else case-insensitive substring.
+public func errorMatches(_ check: ErrorCheck, _ message: String) -> Bool {
+  if check.any {
+    return true
+  }
+  guard let text = check.text else {
+    return false
+  }
+  if check.regex {
+    return regexTest(text, message)
+  }
+  return message.lowercased().contains(text.lowercased())
+}
+
+/// Partial structural match: every leaf of `check` must match `base` at its
+/// path. equal => ok; __UNDEF__ => require absent; __EXISTS__ => require
+/// present; else fall back to matchval. First failure returns its path + the
+/// two values.
+public func structMatch(_ check: JSON, _ base: JSON) -> MatchResult {
+  var result = MatchResult(ok: true)
+  walkLeaves(check, []) { val, path in
+    if !result.ok { return }
+    let baseval = getpath(base, path)
+    if let bv = baseval, jsonEqual(val, bv) {
+      return
+    }
+    if case .str(let s) = val, s == UNDEFMARK, baseval == nil {
+      return
+    }
+    if case .str(let s) = val, s == EXISTSMARK, let bv = baseval, !isJSONNull(bv) {
+      return
+    }
+    if !matchval(val, baseval ?? .null) {
+      result = MatchResult(ok: false, path: path, expected: val, actual: baseval)
+    }
+  }
+  return result
+}
+
+private func isJSONNull(_ v: JSON) -> Bool {
+  if case .null = v { return true }
+  return false
+}
+
+private func isNode(_ v: JSON) -> Bool {
+  return v.isObject || v.isArray
+}
+
+private func walkLeaves(_ node: JSON, _ path: [String], _ fn: (JSON, [String]) -> Void) {
+  switch node {
+  case .arr(let a):
+    for (i, v) in a.enumerated() {
+      walkLeaves(v, path + [String(i)], fn)
+    }
+  case .obj(let p):
+    for (k, v) in p {
+      walkLeaves(v, path + [k], fn)
+    }
+  default:
+    fn(node, path)
+  }
+}
+
+// getpath over the JSON tree. Returns nil when a segment is missing (the
+// equivalent of `undefined` in the canonical reference).
+private func getpath(_ store: JSON, _ path: [String]) -> JSON? {
+  var cur: JSON? = store
+  for key in path {
+    guard let node = cur else { return nil }
+    switch node {
+    case .arr(let a):
+      guard let idx = Int(key), idx >= 0, idx < a.count else { return nil }
+      cur = a[idx]
+    case .obj:
+      cur = node.get(key)  // nil if key absent
+    default:
+      return nil
+    }
+  }
+  return cur
+}
+
+// NSRegularExpression-backed regex test (dependency-free; Foundation only).
+private func regexTest(_ pattern: String, _ subject: String) -> Bool {
+  guard let re = try? NSRegularExpression(pattern: pattern) else { return false }
+  let range = NSRange(subject.startIndex..<subject.endIndex, in: subject)
+  return re.firstMatch(in: subject, options: [], range: range) != nil
+}
diff --git a/test/proto/swift/main.swift b/test/proto/swift/main.swift
new file mode 100644
index 0000000..42bf1af
--- /dev/null
+++ b/test/proto/swift/main.swift
@@ -0,0 +1,53 @@
+// Smoke check for the Swift Test Provider port. Loads the corpus and prints a
+// summary that must match the canonical TS reference numbers.
+//
+// Build/run (when a Swift toolchain is available), from test/proto/swift/:
+//   swiftc Provider.swift smoke.swift -o smoke && ./smoke
+//
+// Expected output:
+//   functions: minor, getpath, inject, merge, transform, walk, validate, select, sentinels
+//   total entries: 1325
+//   expect kinds: value=1181, absent=84, match=1, error=59
+//   input kinds: in=1325, args=0, ctx=0
+//   getpath/basic[0]: id=getpath/basic#deep, doc=true, input.kind=in, expect.kind=value, expect.value=42
+
+import Foundation
+
+let provider = TestProvider.load()
+
+let functions = provider.functions()
+print("functions: " + functions.joined(separator: ", "))
+
+var total = 0
+var expectCounts: [String: Int] = [:]
+var inputCounts: [String: Int] = [:]
+
+for fn in functions {
+  for entry in provider.entries(fn) {
+    total += 1
+    expectCounts[entry.expect.kind.rawValue, default: 0] += 1
+    inputCounts[entry.input.kind.rawValue, default: 0] += 1
+  }
+}
+
+print("total entries: \(total)")
+print(
+  "expect kinds: value=\(expectCounts["value", default: 0]), "
+    + "absent=\(expectCounts["absent", default: 0]), "
+    + "match=\(expectCounts["match", default: 0]), "
+    + "error=\(expectCounts["error", default: 0])")
+print(
+  "input kinds: in=\(inputCounts["in", default: 0]), "
+    + "args=\(inputCounts["args", default: 0]), "
+    + "ctx=\(inputCounts["ctx", default: 0])")
+
+let basic = provider.entries("getpath", group: "basic")
+if let e0 = basic.first {
+  let id = e0.id ?? "<none>"
+  let expectValue = e0.expect.value.map { stringify($0) } ?? "<none>"
+  print(
+    "getpath/basic[0]: id=\(id), doc=\(e0.doc), "
+      + "input.kind=\(e0.input.kind.rawValue), "
+      + "expect.kind=\(e0.expect.kind.rawValue), "
+      + "expect.value=\(expectValue)")
+}
diff --git a/test/proto/ts/provider.ts b/test/proto/ts/provider.ts
new file mode 100644
index 0000000..8b2d596
--- /dev/null
+++ b/test/proto/ts/provider.ts
@@ -0,0 +1,334 @@
+// Test Provider (prototype) — CANONICAL implementation.
+//
+// Reads the shared corpus (build/test/test.json) and hands test code clean,
+// normalized cases. It is NOT a test runner: it never calls the subject and
+// never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+//
+// Zero runtime dependencies (Node built-ins only), matching repo policy.
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const NULLMARK = '__NULL__'
+const UNDEFMARK = '__UNDEF__'
+const EXISTSMARK = '__EXISTS__'
+
+export type InputKind = 'in' | 'args' | 'ctx'
+export type ExpectKind = 'value' | 'error' | 'match' | 'absent'
+
+export interface Input {
+  kind: InputKind
+  in?: any
+  args?: any[]
+  ctx?: Record<string, any>
+}
+
+export interface ErrorCheck {
+  any: boolean
+  text: string | null
+  regex: boolean
+}
+
+export interface Expect {
+  kind: ExpectKind
+  value?: any
+  error?: ErrorCheck
+  match?: any
+}
+
+export interface Entry {
+  function: string
+  group: string
+  index: number
+  id: string | null
+  doc: boolean
+  client: string | null
+  input: Input
+  expect: Expect
+  raw: Record<string, any>
+}
+
+export interface MatchResult {
+  ok: boolean
+  path?: string[]
+  expected?: any
+  actual?: any
+}
+
+// Default corpus path: build/test/test.json relative to the repo root.
+function defaultTestFile(): string {
+  const here = dirname(fileURLToPath(import.meta.url)) // test/proto/ts
+  return join(here, '..', '..', '..', 'build', 'test', 'test.json')
+}
+
+export class TestProvider {
+  readonly spec: any
+
+  constructor(spec: any) {
+    this.spec = spec
+  }
+
+  static load(testfile?: string): TestProvider {
+    const file = testfile ?? defaultTestFile()
+    return new TestProvider(JSON.parse(readFileSync(file, 'utf8')))
+  }
+
+  raw(): any {
+    return this.spec
+  }
+
+  private fnNode(fn: string): Record<string, any> {
+    const node = this.spec?.struct?.[fn] ?? this.spec?.[fn]
+    if (null == node) {
+      throw new Error(`Unknown function: ${fn}`)
+    }
+    return node
+  }
+
+  functions(): string[] {
+    const root = this.spec?.struct ?? this.spec
+    return Object.keys(root).filter((k) => isGroupBag(root[k]) || hasGroups(root[k]))
+  }
+
+  groups(fn: string): string[] {
+    const node = this.fnNode(fn)
+    return Object.keys(node).filter((k) => k !== 'name' && isGroupBag(node[k]))
+  }
+
+  entries(fn: string, group?: string): Entry[] {
+    const node = this.fnNode(fn)
+    const groups = group != null ? [group] : this.groups(fn)
+    const out: Entry[] = []
+    for (const g of groups) {
+      const bag = node[g]
+      if (!isGroupBag(bag)) {
+        continue
+      }
+      const set: any[] = bag.set
+      for (let i = 0; i < set.length; i++) {
+        out.push(normalize(fn, g, i, set[i]))
+      }
+    }
+    return out
+  }
+}
+
+// A group bag is a map with a `set` array.
+function isGroupBag(v: any): boolean {
+  return null != v && 'object' === typeof v && !Array.isArray(v) && Array.isArray(v.set)
+}
+
+// A function node has at least one child group bag.
+function hasGroups(v: any): boolean {
+  return (
+    null != v &&
+    'object' === typeof v &&
+    !Array.isArray(v) &&
+    Object.keys(v).some((k) => k !== 'name' && isGroupBag(v[k]))
+  )
+}
+
+function normalize(fn: string, group: string, index: number, raw: Record<string, any>): Entry {
+  return {
+    function: fn,
+    group,
+    index,
+    id: null != raw.id ? String(raw.id) : null,
+    doc: true === raw.doc,
+    client: null != raw.client ? String(raw.client) : null,
+    input: resolveInput(raw),
+    expect: resolveExpect(raw),
+    raw,
+  }
+}
+
+function has(raw: Record<string, any>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(raw, key)
+}
+
+function resolveInput(raw: Record<string, any>): Input {
+  if (has(raw, 'ctx')) {
+    return { kind: 'ctx', ctx: raw.ctx }
+  }
+  if (has(raw, 'args')) {
+    return { kind: 'args', args: raw.args }
+  }
+  return { kind: 'in', in: has(raw, 'in') ? raw.in : null }
+}
+
+function parseErr(err: any): ErrorCheck {
+  if (true === err) {
+    return { any: true, text: null, regex: false }
+  }
+  if ('string' === typeof err) {
+    const m = err.match(/^\/(.+)\/$/)
+    if (m) {
+      return { any: false, text: m[1], regex: true }
+    }
+    return { any: false, text: err, regex: false }
+  }
+  // Non-true, non-string err spec: treat as "any error".
+  return { any: true, text: null, regex: false }
+}
+
+function resolveExpect(raw: Record<string, any>): Expect {
+  const matchPart = has(raw, 'match') ? raw.match : undefined
+  if (has(raw, 'err')) {
+    return { kind: 'error', error: parseErr(raw.err), match: matchPart }
+  }
+  if (has(raw, 'out')) {
+    return { kind: 'value', value: raw.out, match: matchPart }
+  }
+  if (has(raw, 'match')) {
+    return { kind: 'match', match: raw.match }
+  }
+  return { kind: 'absent' }
+}
+
+// ─── pure comparison helpers ───────────────────────────────────────────────
+
+function stringify(x: any): string {
+  return 'string' === typeof x ? x : JSON.stringify(x)
+}
+
+function normNull(x: any): any {
+  if (NULLMARK === x || undefined === x) {
+    return null
+  }
+  if (Array.isArray(x)) {
+    return x.map(normNull)
+  }
+  if (null != x && 'object' === typeof x) {
+    const o: Record<string, any> = {}
+    for (const k of Object.keys(x)) {
+      o[k] = normNull(x[k])
+    }
+    return o
+  }
+  return x
+}
+
+export function matchval(check: any, base: any): boolean {
+  if (check === base) {
+    return true
+  }
+  if ('string' === typeof check) {
+    const basestr = stringify(base)
+    const rem = check.match(/^\/(.+)\/$/)
+    if (rem) {
+      return new RegExp(rem[1]).test(basestr)
+    }
+    return basestr.toLowerCase().includes(check.toLowerCase())
+  }
+  if ('function' === typeof check) {
+    return true
+  }
+  return false
+}
+
+export function equal(expected: any, actual: any): boolean {
+  return deepEq(normNull(expected), normNull(actual))
+}
+
+// Strict variant for the runner's `{ null: false }` functions, where an absent
+// value (undefined) is distinct from JSON null. Only __NULL__ is normalized.
+export function equalStrict(expected: any, actual: any): boolean {
+  return deepEq(normMark(expected), normMark(actual))
+}
+
+function normMark(x: any): any {
+  if (NULLMARK === x) {
+    return null
+  }
+  if (Array.isArray(x)) {
+    return x.map(normMark)
+  }
+  if (null != x && 'object' === typeof x) {
+    const o: Record<string, any> = {}
+    for (const k of Object.keys(x)) {
+      o[k] = normMark(x[k])
+    }
+    return o
+  }
+  return x
+}
+
+function deepEq(a: any, b: any): boolean {
+  if (a === b) {
+    return true
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => deepEq(v, b[i]))
+  }
+  if (null != a && null != b && 'object' === typeof a && 'object' === typeof b) {
+    const ak = Object.keys(a)
+    const bk = Object.keys(b)
+    return ak.length === bk.length && ak.every((k) => has(b, k) && deepEq(a[k], b[k]))
+  }
+  return false
+}
+
+export function errorMatches(check: ErrorCheck, message: string): boolean {
+  if (check.any) {
+    return true
+  }
+  if (null == check.text) {
+    return false
+  }
+  if (check.regex) {
+    return new RegExp(check.text).test(message)
+  }
+  return message.toLowerCase().includes(check.text.toLowerCase())
+}
+
+// Partial structural match: every leaf of `check` must match `base` at its path.
+export function structMatch(check: any, base: any): MatchResult {
+  let result: MatchResult = { ok: true }
+  walkLeaves(check, [], (val, path) => {
+    if (!result.ok) {
+      return
+    }
+    const baseval = getpath(base, path)
+    if (baseval === val) {
+      return
+    }
+    if (UNDEFMARK === val && undefined === baseval) {
+      return
+    }
+    if (EXISTSMARK === val && null != baseval) {
+      return
+    }
+    if (!matchval(val, baseval)) {
+      result = { ok: false, path, expected: val, actual: baseval }
+    }
+  })
+  return result
+}
+
+function isNode(v: any): boolean {
+  return null != v && 'object' === typeof v
+}
+
+function walkLeaves(node: any, path: string[], fn: (val: any, path: string[]) => void): void {
+  if (Array.isArray(node)) {
+    node.forEach((v, i) => walkLeaves(v, [...path, String(i)], fn))
+  } else if (isNode(node)) {
+    for (const k of Object.keys(node)) {
+      walkLeaves(node[k], [...path, k], fn)
+    }
+  } else {
+    fn(node, path)
+  }
+}
+
+function getpath(store: any, path: string[]): any {
+  let cur = store
+  for (const key of path) {
+    if (null == cur) {
+      return undefined
+    }
+    cur = Array.isArray(cur) ? cur[Number(key)] : cur[key]
+  }
+  return cur
+}
diff --git a/test/proto/ts/smoke.ts b/test/proto/ts/smoke.ts
new file mode 100644
index 0000000..a310496
--- /dev/null
+++ b/test/proto/ts/smoke.ts
@@ -0,0 +1,35 @@
+// Smoke check (not a test): prove the provider loads and normalizes.
+// Run: node --experimental-strip-types test/proto/ts/smoke.ts
+import { TestProvider, equal, equalStrict, errorMatches, structMatch } from './provider.ts'
+
+const p = TestProvider.load()
+const fns = p.functions()
+console.log('functions:', fns.join(', '))
+
+let total = 0
+const kinds: Record<string, number> = {}
+const inkinds: Record<string, number> = {}
+for (const fn of fns) {
+  for (const e of p.entries(fn)) {
+    total++
+    kinds[e.expect.kind] = (kinds[e.expect.kind] ?? 0) + 1
+    inkinds[e.input.kind] = (inkinds[e.input.kind] ?? 0) + 1
+  }
+}
+console.log('total entries:', total)
+console.log('expect kinds:', JSON.stringify(kinds))
+console.log('input kinds:', JSON.stringify(inkinds))
+
+const first = p.entries('getpath', 'basic')[0]
+console.log('sample getpath/basic[0]:', JSON.stringify({
+  id: first.id, doc: first.doc, input: first.input, expect: first.expect,
+}))
+
+// helper sanity
+console.log('equal(42,42):', equal(42, 42))
+console.log('equal(null,undefined):', equal(null, undefined))
+console.log('equalStrict(null,undefined):', equalStrict(null, undefined))
+console.log('errorMatches(any):', errorMatches({ any: true, text: null, regex: false }, 'boom'))
+console.log('errorMatches(substr):', errorMatches({ any: false, text: 'not found', regex: false }, 'Key NOT FOUND here'))
+console.log('structMatch ok:', structMatch({ a: { b: 2 } }, { a: { b: 2 }, c: 9 }).ok)
+console.log('structMatch fail:', JSON.stringify(structMatch({ a: { b: 2 } }, { a: { b: 3 } })))
diff --git a/test/proto/zig/provider.zig b/test/proto/zig/provider.zig
new file mode 100644
index 0000000..571e7e4
--- /dev/null
+++ b/test/proto/zig/provider.zig
@@ -0,0 +1,660 @@
+// Test Provider (prototype) — Zig port of the canonical TypeScript
+// implementation (../ts/provider.ts).
+//
+// Reads the shared corpus (build/test/test.json) and hands test code clean,
+// normalized cases. It is NOT a test runner: it never calls the subject and
+// never asserts. See ../PROVIDER.md for the model and ../AGENTS.md for usage.
+//
+// Zero runtime dependencies (Zig standard library only — std.json is stdlib),
+// matching repo policy. Tested-against API: Zig 0.13.0, same as
+// ../../../zig/test/runner.zig (std.json.parseFromSlice + std.json.Value).
+//
+// std.json.Value's `.object` is a std.json.ObjectMap, which is backed by an
+// array hash map: it preserves *insertion order*, so iterating its keys yields
+// corpus-faithful ordering for functions()/groups() without a side table (the
+// Go port needs one only because encoding/json drops key order).
+
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+const Value = std.json.Value;
+const ObjectMap = std.json.ObjectMap;
+
+pub const NULLMARK = "__NULL__";
+pub const UNDEFMARK = "__UNDEF__";
+pub const EXISTSMARK = "__EXISTS__";
+
+// Default corpus path, relative to this source file's directory
+// (test/proto/zig). The runner is typically invoked from the proto/zig dir.
+pub const DEFAULT_TEST_FILE = "../../../build/test/test.json";
+
+pub const InputKind = enum { in, args, ctx };
+pub const ExpectKind = enum { value, error_, match, absent };
+
+// Tagged invocation: exactly one of in/args/ctx is meaningful, selected by
+// `kind` (mirrors the runner's ctx -> args -> in precedence).
+//
+// `in` carries `null` for kind == .in when the raw entry has no "in" key
+// (native null per §3). To distinguish "absent" from an explicit JSON null we
+// keep `has_in`: when kind == .in and has_in is false, the corpus had no key.
+pub const Input = struct {
+    kind: InputKind,
+    has_in: bool = false,
+    in: ?Value = null,
+    args: ?Value = null, // a JSON array value when kind == .args
+    ctx: ?Value = null, // a JSON object value when kind == .ctx
+};
+
+// Parsed form of a raw `err` spec.
+pub const ErrorCheck = struct {
+    any: bool = false,
+    text: ?[]const u8 = null,
+    regex: bool = false,
+};
+
+// Tagged expectation: value | error | match | absent.
+pub const Expect = struct {
+    kind: ExpectKind,
+    // kind == .value — expected result (may be literal JSON null). has_value
+    // distinguishes a present-null `out` from an absent one.
+    has_value: bool = false,
+    value: ?Value = null,
+    error_: ?ErrorCheck = null,
+    // Populated whenever a `match` key is present (even alongside err/out).
+    has_match: bool = false,
+    match: ?Value = null,
+};
+
+// Normalized record for a single corpus test case.
+pub const Entry = struct {
+    function: []const u8,
+    group: []const u8,
+    index: usize,
+    id: ?[]const u8,
+    doc: bool,
+    client: ?[]const u8,
+    input: Input,
+    expect: Expect,
+    raw: Value,
+};
+
+// Outcome of a structural match.
+pub const MatchResult = struct {
+    ok: bool,
+    path: ?[][]const u8 = null,
+    expected: ?Value = null,
+    actual: ?Value = null,
+};
+
+pub const TestProvider = struct {
+    allocator: Allocator,
+    parsed: std.json.Parsed(Value),
+    file_data: []const u8,
+    spec: Value,
+
+    /// Parse test.json. Pass null for `testfile` to use the default corpus
+    /// path (../../../build/test/test.json relative to this source's dir).
+    pub fn load(allocator: Allocator, testfile: ?[]const u8) !TestProvider {
+        const path = testfile orelse DEFAULT_TEST_FILE;
+        const data = try std.fs.cwd().readFileAlloc(allocator, path, 64 * 1024 * 1024);
+        const parsed = try std.json.parseFromSlice(Value, allocator, data, .{});
+        return TestProvider{
+            .allocator = allocator,
+            .parsed = parsed,
+            .file_data = data,
+            .spec = parsed.value,
+        };
+    }
+
+    pub fn deinit(self: *TestProvider) void {
+        self.parsed.deinit();
+        self.allocator.free(self.file_data);
+    }
+
+    /// The parsed test.json (escape hatch).
+    pub fn raw(self: TestProvider) Value {
+        return self.spec;
+    }
+
+    // spec.struct if present, else spec itself, as an object map.
+    fn root(self: TestProvider) ?*const ObjectMap {
+        if (self.spec != .object) return null;
+        if (self.spec.object.getPtr("struct")) |s| {
+            if (s.* == .object) return &s.object;
+        }
+        return &self.spec.object;
+    }
+
+    // The node for a function (under struct, falling back to root).
+    fn fnNode(self: TestProvider, fn_name: []const u8) ?*const ObjectMap {
+        if (self.spec != .object) return null;
+        if (self.spec.object.getPtr("struct")) |s| {
+            if (s.* == .object) {
+                if (s.object.getPtr(fn_name)) |n| {
+                    if (n.* == .object) return &n.object;
+                }
+            }
+        }
+        if (self.spec.object.getPtr(fn_name)) |n| {
+            if (n.* == .object) return &n.object;
+        }
+        return null;
+    }
+
+    /// Function names in corpus (insertion) order. Caller owns the returned
+    /// slice (allocated with `alloc`); the strings borrow the parsed JSON.
+    pub fn functions(self: TestProvider, alloc: Allocator) ![][]const u8 {
+        var out = std.ArrayList([]const u8).init(alloc);
+        const r = self.root() orelse return out.toOwnedSlice();
+        var it = r.iterator();
+        while (it.next()) |kv| {
+            const v = kv.value_ptr.*;
+            if (isGroupBag(v) or hasGroups(v)) {
+                try out.append(kv.key_ptr.*);
+            }
+        }
+        return out.toOwnedSlice();
+    }
+
+    /// Group names for a function in corpus order. Caller owns the slice.
+    pub fn groups(self: TestProvider, alloc: Allocator, fn_name: []const u8) ![][]const u8 {
+        var out = std.ArrayList([]const u8).init(alloc);
+        const node = self.fnNode(fn_name) orelse return out.toOwnedSlice();
+        var it = node.iterator();
+        while (it.next()) |kv| {
+            const k = kv.key_ptr.*;
+            if (!std.mem.eql(u8, k, "name") and isGroupBag(kv.value_ptr.*)) {
+                try out.append(k);
+            }
+        }
+        return out.toOwnedSlice();
+    }
+
+    /// All entries for a function across its groups. Caller owns the slice.
+    pub fn entries(self: TestProvider, alloc: Allocator, fn_name: []const u8) ![]Entry {
+        return self.entriesImpl(alloc, fn_name, null);
+    }
+
+    /// Entries for one specific group of a function. Caller owns the slice.
+    pub fn entriesGroup(self: TestProvider, alloc: Allocator, fn_name: []const u8, group: []const u8) ![]Entry {
+        return self.entriesImpl(alloc, fn_name, group);
+    }
+
+    fn entriesImpl(self: TestProvider, alloc: Allocator, fn_name: []const u8, group: ?[]const u8) ![]Entry {
+        var out = std.ArrayList(Entry).init(alloc);
+        const node = self.fnNode(fn_name) orelse return out.toOwnedSlice();
+
+        const group_names = if (group) |g|
+            try alloc.dupe([]const u8, &[_][]const u8{g})
+        else
+            try self.groups(alloc, fn_name);
+
+        for (group_names) |g| {
+            const bag_ptr = node.getPtr(g) orelse continue;
+            const bag = bag_ptr.*;
+            if (!isGroupBag(bag)) continue;
+            const set = bag.object.get("set").?; // isGroupBag guarantees .set array
+            const items = set.array.items;
+            for (items, 0..) |raw_val, i| {
+                try out.append(normalize(fn_name, g, i, raw_val));
+            }
+        }
+        return out.toOwnedSlice();
+    }
+};
+
+// A group bag is an object containing a `set` array.
+fn isGroupBag(v: Value) bool {
+    if (v != .object) return false;
+    const set = v.object.get("set") orelse return false;
+    return set == .array;
+}
+
+// A function node is an object with at least one child group bag.
+fn hasGroups(v: Value) bool {
+    if (v != .object) return false;
+    var it = v.object.iterator();
+    while (it.next()) |kv| {
+        if (!std.mem.eql(u8, kv.key_ptr.*, "name") and isGroupBag(kv.value_ptr.*)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+// KEY PRESENCE check (object.contains) — NOT a null-check. This is what makes
+// `out: null` resolve to VALUE rather than ABSENT (§4).
+fn has(obj: ObjectMap, key: []const u8) bool {
+    return obj.contains(key);
+}
+
+fn normalize(fn_name: []const u8, group: []const u8, index: usize, raw_val: Value) Entry {
+    // raw entries are always objects in the corpus; guard defensively.
+    if (raw_val != .object) {
+        return Entry{
+            .function = fn_name,
+            .group = group,
+            .index = index,
+            .id = null,
+            .doc = false,
+            .client = null,
+            .input = Input{ .kind = .in, .has_in = false, .in = null },
+            .expect = Expect{ .kind = .absent },
+            .raw = raw_val,
+        };
+    }
+    const obj = raw_val.object;
+
+    var id: ?[]const u8 = null;
+    if (obj.get("id")) |v| {
+        if (v != .null) id = stringifyId(v);
+    }
+    var client: ?[]const u8 = null;
+    if (obj.get("client")) |v| {
+        if (v != .null) client = stringifyId(v);
+    }
+    const doc = if (obj.get("doc")) |v| (v == .bool and v.bool == true) else false;
+
+    return Entry{
+        .function = fn_name,
+        .group = group,
+        .index = index,
+        .id = id,
+        .doc = doc,
+        .client = client,
+        .input = resolveInput(obj),
+        .expect = resolveExpect(obj),
+        .raw = raw_val,
+    };
+}
+
+// For id/client we only ever expect strings in the corpus; if not a string,
+// fall back to the borrowed JSON string when present, else a literal label.
+// (The TS port does String(raw.id); we keep the borrowed slice for strings.)
+fn stringifyId(v: Value) ?[]const u8 {
+    return switch (v) {
+        .string => |s| s,
+        .number_string => |s| s,
+        else => null,
+    };
+}
+
+fn resolveInput(obj: ObjectMap) Input {
+    if (has(obj, "ctx")) {
+        return Input{ .kind = .ctx, .ctx = obj.get("ctx").? };
+    }
+    if (has(obj, "args")) {
+        return Input{ .kind = .args, .args = obj.get("args").? };
+    }
+    if (has(obj, "in")) {
+        return Input{ .kind = .in, .has_in = true, .in = obj.get("in").? };
+    }
+    // No "in" key => native null.
+    return Input{ .kind = .in, .has_in = false, .in = null };
+}
+
+fn parseErr(err: Value) ErrorCheck {
+    switch (err) {
+        .bool => |b| if (b) return ErrorCheck{ .any = true },
+        .string => |s| {
+            // "/re/" => regex; other string => literal substring text.
+            if (s.len >= 3 and s[0] == '/' and s[s.len - 1] == '/') {
+                return ErrorCheck{ .any = false, .text = s[1 .. s.len - 1], .regex = true };
+            }
+            return ErrorCheck{ .any = false, .text = s, .regex = false };
+        },
+        else => {},
+    }
+    // Non-true, non-string err spec: treat as "any error".
+    return ErrorCheck{ .any = true };
+}
+
+fn resolveExpect(obj: ObjectMap) Expect {
+    const has_match = has(obj, "match");
+    const match_part: ?Value = if (has_match) obj.get("match").? else null;
+
+    // 1. err -> ERROR
+    if (has(obj, "err")) {
+        return Expect{
+            .kind = .error_,
+            .error_ = parseErr(obj.get("err").?),
+            .has_match = has_match,
+            .match = match_part,
+        };
+    }
+    // 2. out present (KEY PRESENCE, even if JSON null) -> VALUE
+    if (has(obj, "out")) {
+        return Expect{
+            .kind = .value,
+            .has_value = true,
+            .value = obj.get("out").?,
+            .has_match = has_match,
+            .match = match_part,
+        };
+    }
+    // 3. match -> MATCH
+    if (has_match) {
+        return Expect{ .kind = .match, .has_match = true, .match = match_part };
+    }
+    // 4. ABSENT
+    return Expect{ .kind = .absent };
+}
+
+// ─── pure comparison helpers ───────────────────────────────────────────────
+
+/// stringify(x) = x if it is already a string, else compact JSON.
+/// Result is allocated with `alloc` (caller owns it) except the string case,
+/// which borrows. Use `allocStringify` when you need a uniform owned buffer.
+pub fn stringify(alloc: Allocator, x: Value) ![]const u8 {
+    if (x == .string) return x.string;
+    var buf = std.ArrayList(u8).init(alloc);
+    errdefer buf.deinit();
+    try std.json.stringify(x, .{}, buf.writer());
+    return buf.toOwnedSlice();
+}
+
+fn normVal(x: Value) Value {
+    // Collapse the "__NULL__" sentinel to a real null (mirrors normNull leaf).
+    if (x == .string and std.mem.eql(u8, x.string, NULLMARK)) return Value{ .null = {} };
+    return x;
+}
+
+/// Deep equality collapsing "__NULL__" (and absent, treated as null at leaves)
+/// to null on both sides. Mirrors the runner's `flags.null == true` round-trip.
+pub fn equal(expected: Value, actual: Value) bool {
+    return deepEq(expected, actual, true);
+}
+
+/// Strict deep equality: only "__NULL__" is normalized to null; absent and
+/// JSON null stay distinct (the runner's `null:false` functions). Within
+/// std.json.Value both sides are already concrete, so the only difference from
+/// `equal` is whether we further collapse — here we still normalize __NULL__.
+pub fn equalStrict(expected: Value, actual: Value) bool {
+    return deepEq(expected, actual, false);
+}
+
+// collapse_null: when true, a leaf null and a missing object key are treated
+// equivalently. Both modes normalize the __NULL__ string sentinel.
+fn deepEq(a_in: Value, b_in: Value, collapse_null: bool) bool {
+    const a = normVal(a_in);
+    const b = normVal(b_in);
+
+    const TagType = std.meta.Tag(Value);
+    const ta: TagType = a;
+    const tb: TagType = b;
+
+    // Numeric cross-type equality (integer vs float).
+    if ((ta == .integer or ta == .float) and (tb == .integer or tb == .float)) {
+        const fa: f64 = if (ta == .integer) @floatFromInt(a.integer) else a.float;
+        const fb: f64 = if (tb == .integer) @floatFromInt(b.integer) else b.float;
+        return fa == fb;
+    }
+
+    if (ta != tb) return false;
+
+    return switch (a) {
+        .null => true,
+        .bool => |av| av == b.bool,
+        .integer => |av| av == b.integer,
+        .float => |av| av == b.float,
+        .number_string => |av| std.mem.eql(u8, av, b.number_string),
+        .string => |av| std.mem.eql(u8, av, b.string),
+        .array => |av| {
+            const bv = b.array;
+            if (av.items.len != bv.items.len) return false;
+            for (av.items, bv.items) |ai, bi| {
+                if (!deepEq(ai, bi, collapse_null)) return false;
+            }
+            return true;
+        },
+        .object => |av| {
+            const bv = b.object;
+            if (collapse_null) {
+                // Keys whose value is null on one side may be absent on the
+                // other; compare on the union, treating absent as null.
+                if (!objEqCollapse(av, bv)) return false;
+                if (!objEqCollapse(bv, av)) return false;
+                return true;
+            }
+            if (av.count() != bv.count()) return false;
+            var it = av.iterator();
+            while (it.next()) |kv| {
+                const bval = bv.get(kv.key_ptr.*) orelse return false;
+                if (!deepEq(kv.value_ptr.*, bval, collapse_null)) return false;
+            }
+            return true;
+        },
+    };
+}
+
+fn isNullish(v: Value) bool {
+    if (v == .null) return true;
+    if (v == .string and std.mem.eql(u8, v.string, NULLMARK)) return true;
+    return false;
+}
+
+// Every key of `a` must equal the corresponding key of `b`, where a missing
+// key in `b` counts as null (so null == absent under collapse semantics).
+fn objEqCollapse(a: ObjectMap, b: ObjectMap) bool {
+    var it = a.iterator();
+    while (it.next()) |kv| {
+        const av = kv.value_ptr.*;
+        if (b.get(kv.key_ptr.*)) |bv| {
+            if (!deepEq(av, bv, true)) return false;
+        } else {
+            // absent on the other side == null
+            if (!isNullish(av)) return false;
+        }
+    }
+    return true;
+}
+
+/// matchval(check, base): deep-equal (strict), then string rules:
+///   "/re/"  => RegExp(re).test(stringify(base))
+///   string  => stringify(base).toLowerCase() contains check.toLowerCase()
+/// A "function" check is always true in TS; not representable here.
+pub fn matchval(alloc: Allocator, check: Value, base: Value) bool {
+    if (equalStrict(check, base)) return true;
+    if (check == .string) {
+        const basestr = stringify(alloc, base) catch return false;
+        const cs = check.string;
+        if (cs.len >= 3 and cs[0] == '/' and cs[cs.len - 1] == '/') {
+            return regexTest(cs[1 .. cs.len - 1], basestr);
+        }
+        return containsCaseInsensitive(basestr, cs);
+    }
+    return false;
+}
+
+// Case-insensitive substring (ASCII). Mirrors
+// stringify(base).toLowerCase().includes(check.toLowerCase()).
+fn containsCaseInsensitive(haystack: []const u8, needle: []const u8) bool {
+    if (needle.len == 0) return true;
+    if (needle.len > haystack.len) return false;
+    var i: usize = 0;
+    const last = haystack.len - needle.len;
+    while (i <= last) : (i += 1) {
+        var j: usize = 0;
+        while (j < needle.len) : (j += 1) {
+            if (std.ascii.toLower(haystack[i + j]) != std.ascii.toLower(needle[j])) break;
+        }
+        if (j == needle.len) return true;
+    }
+    return false;
+}
+
+/// errorMatches(check, message): any => true; regex => RegExp(text).test(msg);
+/// else case-insensitive substring.
+pub fn errorMatches(check: ErrorCheck, message: []const u8) bool {
+    if (check.any) return true;
+    const text = check.text orelse return false;
+    if (check.regex) return regexTest(text, message);
+    return containsCaseInsensitive(message, text);
+}
+
+// ── minimal regex matcher ──────────────────────────────────────────────────
+//
+// SIMPLIFICATION: the std library has no general regex engine. This is a tiny
+// fallback supporting only unanchored literal substring matching (with `.` as
+// any-char). It is sufficient for the corpus's "/re/" error checks, which are
+// predominantly plain substrings. Patterns using real regex metacharacters
+// (alternation, classes, quantifiers, anchors) are NOT fully supported and
+// will degrade to a literal-ish scan. Documented here as a known limitation;
+// the canonical TS/Go ports use their host regex engine.
+fn regexTest(pattern: []const u8, text: []const u8) bool {
+    // Fast path: if the pattern has no metacharacters, it's a substring test.
+    var plain = true;
+    for (pattern) |c| {
+        switch (c) {
+            '.', '*', '+', '?', '(', ')', '[', ']', '{', '}', '|', '^', '$', '\\' => {
+                plain = false;
+                break;
+            },
+            else => {},
+        }
+    }
+    if (plain) return std.mem.indexOf(u8, text, pattern) != null;
+    return regexMatchAnywhere(pattern, text);
+}
+
+// `.`-aware unanchored matcher: tries to match `pattern` (with `.` = any char)
+// as a contiguous run starting at each position. Other metacharacters are
+// treated literally (best effort).
+fn regexMatchAnywhere(pattern: []const u8, text: []const u8) bool {
+    const anchored_start = pattern.len > 0 and pattern[0] == '^';
+    const pat = if (anchored_start) pattern[1..] else pattern;
+    if (anchored_start) return regexMatchAt(pat, text, 0);
+    if (text.len < pat.len) {
+        // still allow empty pattern
+        if (pat.len == 0) return true;
+        return false;
+    }
+    var i: usize = 0;
+    while (i + pat.len <= text.len) : (i += 1) {
+        if (regexMatchAt(pat, text, i)) return true;
+    }
+    return false;
+}
+
+fn regexMatchAt(pat: []const u8, text: []const u8, start: usize) bool {
+    var anchored_end = false;
+    var p = pat;
+    if (p.len > 0 and p[p.len - 1] == '$') {
+        anchored_end = true;
+        p = p[0 .. p.len - 1];
+    }
+    if (start + p.len > text.len) return false;
+    var k: usize = 0;
+    while (k < p.len) : (k += 1) {
+        if (p[k] == '.') continue;
+        if (p[k] != text[start + k]) return false;
+    }
+    if (anchored_end and start + p.len != text.len) return false;
+    return true;
+}
+
+// ── structural match ────────────────────────────────────────────────────────
+
+/// structMatch(check, base): every leaf of `check` must match `base` at its
+/// path. equal leaf => ok; __UNDEF__ => require absent; __EXISTS__ => require
+/// present; else fall back to matchval. First failure returns its path + both
+/// values. Allocations (the failing path, scratch strings) use `alloc`.
+pub fn structMatch(alloc: Allocator, check: Value, base: Value) MatchResult {
+    var result = MatchResult{ .ok = true };
+    var path = std.ArrayList([]const u8).init(alloc);
+    defer path.deinit();
+    walkLeaves(alloc, check, &path, base, &result);
+    return result;
+}
+
+fn walkLeaves(
+    alloc: Allocator,
+    node: Value,
+    path: *std.ArrayList([]const u8),
+    base: Value,
+    result: *MatchResult,
+) void {
+    if (!result.ok) return;
+    switch (node) {
+        .array => |arr| {
+            for (arr.items, 0..) |child, i| {
+                var buf: [24]u8 = undefined;
+                const seg = std.fmt.bufPrint(&buf, "{d}", .{i}) catch "?";
+                // Duplicate so the segment survives buf going out of scope.
+                const owned = alloc.dupe(u8, seg) catch return;
+                path.append(owned) catch return;
+                walkLeaves(alloc, child, path, base, result);
+                _ = path.pop();
+                if (!result.ok) return;
+            }
+        },
+        .object => |obj| {
+            var it = obj.iterator();
+            while (it.next()) |kv| {
+                path.append(kv.key_ptr.*) catch return;
+                walkLeaves(alloc, kv.value_ptr.*, path, base, result);
+                _ = path.pop();
+                if (!result.ok) return;
+            }
+        },
+        else => {
+            checkLeaf(alloc, node, path.items, base, result);
+        },
+    }
+}
+
+fn checkLeaf(
+    alloc: Allocator,
+    val: Value,
+    path: []const []const u8,
+    base: Value,
+    result: *MatchResult,
+) void {
+    const found = getpath(base, path);
+    const baseval: Value = found orelse Value{ .null = {} };
+
+    // equal leaf (strict) => ok
+    if (found != null and equalStrict(val, baseval)) return;
+
+    // __UNDEF__ => require absent
+    if (val == .string and std.mem.eql(u8, val.string, UNDEFMARK)) {
+        if (found == null or baseval == .null) return;
+    }
+    // __EXISTS__ => require present (and non-null)
+    if (val == .string and std.mem.eql(u8, val.string, EXISTSMARK)) {
+        if (found != null and baseval != .null) return;
+    }
+    if (!matchval(alloc, val, baseval)) {
+        // Record a stable copy of the failing path.
+        const owned = alloc.alloc([]const u8, path.len) catch {
+            result.* = MatchResult{ .ok = false, .expected = val, .actual = if (found != null) baseval else null };
+            return;
+        };
+        std.mem.copyForwards([]const u8, owned, path);
+        result.* = MatchResult{
+            .ok = false,
+            .path = owned,
+            .expected = val,
+            .actual = if (found != null) baseval else null,
+        };
+    }
+}
+
+// Descend `store` following string path segments. Returns null if it runs off
+// a null/missing key or an out-of-range/non-numeric array index.
+fn getpath(store: Value, path: []const []const u8) ?Value {
+    var cur = store;
+    for (path) |key| {
+        switch (cur) {
+            .object => |obj| {
+                cur = obj.get(key) orelse return null;
+            },
+            .array => |arr| {
+                const idx = std.fmt.parseInt(usize, key, 10) catch return null;
+                if (idx >= arr.items.len) return null;
+                cur = arr.items[idx];
+            },
+            else => return null,
+        }
+    }
+    return cur;
+}
diff --git a/test/proto/zig/smoke.zig b/test/proto/zig/smoke.zig
new file mode 100644
index 0000000..07883a2
--- /dev/null
+++ b/test/proto/zig/smoke.zig
@@ -0,0 +1,118 @@
+// Smoke test for the Zig test-provider port. Prints a small summary of the
+// loaded corpus so the numbers can be eyeballed against the canonical target:
+//
+//   functions: minor, getpath, inject, merge, transform, walk, validate,
+//              select, sentinels
+//   total entries: 1325
+//   expect kinds: value=1181, absent=84, match=1, error=59
+//   input  kinds: in=1325
+//   getpath/basic[0]: id=getpath/basic#deep, doc=true, input.kind=in,
+//                     expect.kind=value, expect.value=42
+//
+// Run (Zig 0.13): from test/proto/zig/  ->  zig run smoke.zig
+// (No build.zig needed; provider.zig is a plain stdlib-only module.)
+
+const std = @import("std");
+const provider = @import("provider.zig");
+
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+    const g0 = gpa.allocator();
+
+    // Use an arena for all transient provider output (function/group/entry
+    // slices), freed at the end.
+    var arena = std.heap.ArenaAllocator.init(g0);
+    defer arena.deinit();
+    const a = arena.allocator();
+
+    const stdout = std.io.getStdOut().writer();
+
+    var tp = try provider.TestProvider.load(g0, null);
+    defer tp.deinit();
+
+    // ── functions list ──
+    const fns = try tp.functions(a);
+    try stdout.writeAll("functions: ");
+    for (fns, 0..) |f, i| {
+        if (i != 0) try stdout.writeAll(", ");
+        try stdout.writeAll(f);
+    }
+    try stdout.writeAll("\n");
+
+    // ── totals + expect/input kind counts ──
+    var total: usize = 0;
+    var ev: usize = 0; // value
+    var ea: usize = 0; // absent
+    var em: usize = 0; // match
+    var ee: usize = 0; // error
+    var ii: usize = 0; // input .in
+    var ia: usize = 0; // input .args
+    var ic: usize = 0; // input .ctx
+
+    for (fns) |f| {
+        const es = try tp.entries(a, f);
+        total += es.len;
+        for (es) |e| {
+            switch (e.expect.kind) {
+                .value => ev += 1,
+                .absent => ea += 1,
+                .match => em += 1,
+                .error_ => ee += 1,
+            }
+            switch (e.input.kind) {
+                .in => ii += 1,
+                .args => ia += 1,
+                .ctx => ic += 1,
+            }
+        }
+    }
+
+    try stdout.print("total entries: {d}\n", .{total});
+    try stdout.print("expect kinds: value={d}, absent={d}, match={d}, error={d}\n", .{ ev, ea, em, ee });
+    try stdout.print("input kinds: in={d}", .{ii});
+    if (ia != 0) try stdout.print(", args={d}", .{ia});
+    if (ic != 0) try stdout.print(", ctx={d}", .{ic});
+    try stdout.writeAll("\n");
+
+    // ── getpath/basic[0] spotlight ──
+    const gb = try tp.entriesGroup(a, "getpath", "basic");
+    if (gb.len > 0) {
+        const e = gb[0];
+        const id = e.id orelse "<null>";
+        try stdout.print("getpath/basic[0]: id={s}, doc={}, input.kind={s}, expect.kind={s}, expect.value=", .{
+            id,
+            e.doc,
+            @tagName(e.input.kind),
+            expectKindName(e.expect.kind),
+        });
+        if (e.expect.value) |v| {
+            try printValue(stdout, v);
+        } else {
+            try stdout.writeAll("<none>");
+        }
+        try stdout.writeAll("\n");
+    } else {
+        try stdout.writeAll("getpath/basic[0]: <no entries>\n");
+    }
+}
+
+fn expectKindName(k: provider.ExpectKind) []const u8 {
+    return switch (k) {
+        .value => "value",
+        .error_ => "error",
+        .match => "match",
+        .absent => "absent",
+    };
+}
+
+fn printValue(writer: anytype, v: std.json.Value) !void {
+    switch (v) {
+        .integer => |n| try writer.print("{d}", .{n}),
+        .float => |n| try writer.print("{d}", .{n}),
+        .string => |s| try writer.writeAll(s),
+        .bool => |b| try writer.print("{}", .{b}),
+        .null => try writer.writeAll("null"),
+        else => try std.json.stringify(v, .{}, writer),
+    }
+}