spike: spock gen provider — assembly-layer tables from the contract

[k08200]

Summary

Evidence spike for gridaco/uhura#29: the client-owned assembly layer between the contract and an app (projections, intent-to-fn mapping, refusal policy — 2,089 hand-written lines in the uhura instagram provider) declared in one per-app file and generated by the binary, where RFD 0010 assigns generation. Draft on purpose; the declaration syntax is a spike and nothing here is proposed for adoption.

spock gen provider <program.spock> --app <app.wire> [-o out.mjs]

Compiles the program, consumes the typed contract in-process (no JSON seam), validates every table / fn / error the declaration references, and emits the provider tables module: snapshot GraphQL document, machine contract types, dispatch switch, refusal whitelist, mutation routing, and the Play asset table. The generic runtime the tables plug into travels under tests/provider_runtime/ with a fake-server harness and a live-server E2E script.

Change classification

• Language-contract-preserving implementation, tooling, documentation, tests, or refactor
• Isolated, opt-in, non-normative pre-1.0 experiment or prototype
• Committee-sponsored RFD draft, review revision, or decision record
• Implementation or specification synchronization authorized by an accepted RFD
• Non-normative working-group study or meeting record
• Governance or contribution-process change

Language-change gate

• Related issue: RFD: the assembly layer between the Spock contract and an app uhura#29
• Language-problem issue: n/a — no language-contract change requested
• Committee sponsor/shepherd: n/a — not an RFD PR
• Accepted RFD: n/a — changes no supported or default behavior; placement follows RFD 0010's generator-ownership decision without extending it
• Implementation tracking issue: n/a
• Language-contract preservation: the contract is consumed read-only through the existing typed IR; no specified syntax, semantics, or docs/spec text changes
• Experiment boundary: entry point is the new spock gen provider subcommand only — nothing invokes it by default; code is isolated in crates/spock-cli/src/provider_gen/ with its own fixtures/tests; default validation and all existing suites unchanged; owner @yongrean; review at the disposition of RFD: the assembly layer between the Spock contract and an app uhura#29, removal is a single directory plus one match arm

Before and after

Before: every app hand-writes its provider assembly (the uhura instagram example carries 2,089 lines: snapshot query, dispatch, refusal whitelist, asset table, projections).

After (opt-in only): spock gen provider emits the equivalent tables module from a 91-line declaration, char-equal with the hand-written artifacts. Default behavior is unchanged; no existing command or output differs.

Scope and tradeoffs

Out of scope: the declaration syntax itself (spike vocabulary, not proposed), shipping the generic runtime, uhura machine-type generation ownership, and any normative documentation. New dependencies (pest, pest_derive, serde) are limited to spock-cli. Removal cost is one directory and one subcommand arm.

Verification

• cargo test -p spock-cli — 29 + 15 + 9 green (nine new goldens hold each generated artifact char-equal with the hand-written instagram provider; fixtures mechanically extracted from the uhura example, MIT © Grida; each golden shown to fail on injected errors)

• cargo test -p spock-cli --test provider_gen -- --ignored — opt-in node harness executes the emitted module against the shared runtime (branching, three settlement paths, queue serialization); never a CI requirement

• tests/provider_runtime/e2e.mjs run against a live spock start backend: generated snapshot query accepted with exact seed counts, like/unlike round-trip restores state, unauthenticated refusal code matches the generated whitelist

• contract_exposes_the_storage_object_system_table records why the contract (not .spock source parsing) is the input: source parsing missed the compiler-owned 11th table

• cargo clippy -p spock-cli --all-targets clean; workspace build clean

• I read and followed CONTRIBUTING.md.

• I added or updated focused tests, or explained why no test applies.

• I updated user-facing documentation and the normative specification when authorized behavior changed.

• I kept unrelated changes out of this PR.

• If this is experimental, I prominently marked it and kept it isolated from default behavior, the normative specification, and conformance expectations.

• I have not presented a working-group study or community preference as an accepted language decision.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spock	Ready	Preview, Comment	Jul 23, 2026 12:28pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9253f94a-4ff2-4874-b9b7-1cb956497577

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch spike/gen-provider

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}