A specification for a Solidus API toolkit against a Prism-mocked contract. Originally three files; grown to include reification and a demo mock.
Normative spec:
README.org— this file.spec.org— the spec (current head: v1.7).CLAUDE.md— agent instructions.
Scaffold:
GNUmakefile— reify OAS, run demo mock, print MCP config..gitignore— ignore.spec-cache/,.env, mock-runtime state.docs/examples.org— non-normative live-Solidus verification shape reference.
Demo mock (deliberate constraint violation — see §Demo mock exception):
mocks/msw/— MSW-backed demo mock, real-shaped Solidus data (12 products, 2 taxonomies, historical + session orders, cart-consistent).demos/— asciinema/agg scripts producing the CLI / TUI / MCP demo GIFs shown below..mcp.json— wires theliquidus-005MCP server into Claude Code sessions launched from this dir.
The name is the phase-diagram counterpart to solidus: the temperature boundary above which an alloy is fully molten. Apt because everything here happens in the pre-commitment phase — the API contract exists, but no toolkit implementation has solidified yet.
Recorded against the demo mock (gmake demo-mock). Consumer CLIs, TUIs, and MCP servers all point at http://localhost:4010 with the stub bearer.
- CLI:
demos/gifs/cli.gif— RubyliquidusCLI (liquidus-006), curated Solidus data. - TUI:
demos/gifs/tui.gif— Rubyliquidus-tui(liquidus-006), slash-command palette. - MCP:
demos/gifs/mcp.gif— Python liquidus-mcp (liquidus-005), F5 provenance wrapping.
The public repo’s foundational discipline (CLAUDE.md §Public repo scope: three files, no code) is deliberately violated by mocks/msw/ and demos/. The exception is documented, not slipped in.
Why the exception exists. The v0–v1.7 grind demonstrated that Prism’s schema-noise output ("string" for every string field, 0 for every integer) is technically correct but useless for demonstration and unusable for a wired-in MCP tool call. Shipping a curated MSW mock with real Solidus-shaped data is the only way to let a downstream (Claude Code, a demo terminal, a screenshot for a blog post) exercise the toolkit end-to-end.
Recommended mock: MSW for exploration and demos (this repo’s mocks/msw/); Prism for strict-contract automated tests (liquidus-001).
Boundary of the violation.
- The mock’s shape must always match the reified OAS at the pinned SHA. Any drift is a bug in
mocks/msw/, not in the spec. - The mock has no separate spec revision — it tracks the same version as the whole repo.
- The mock MUST NOT ship logic that a real Solidus wouldn’t have (no custom endpoints, no computed fields absent from the OAS).
- Wire-in to Claude Code via
.mcp.jsonpoints at theliquidus-005MCP server which itself points atlocalhost:4010(the demo mock). This chain is the deliberate reference topology; do not reproduce it in production.
If the exception grows. Anything beyond mocks/msw/ + demos/ + .mcp.json suggests the spec is not enough. That is a spec bug, not a scope creep — fold it back into spec.org before adding another file to the public repo.
- Not a mock server. The spec calls for one; it doesn’t ship one.
- Not an SDK. It calls for one generated from a pinned OpenAPI SHA; the generation happens elsewhere.
- Not a CLI, TUI, or MCP server. See below.
If you’re looking for the implementation, you’re looking in the wrong repo.
Each grind unit lives in its own private validation repo. Each build takes only the three files in this repo as input and produces a working implementation of a single grind unit. When a build lands, it also lands a FEEDBACK.md against the public spec — the build teams grade the spec, not the other way around.
| Repo | Grind unit | Language / runtime | Status |
|---|---|---|---|
| liquidus-001 | Mocking framework | Prism baseline + one alternative | v0 |
| liquidus-002 | CLI/TUI | Python (typer + textual) | queued |
| liquidus-003 | CLI/TUI | Go (cobra + bubbletea) | queued |
| liquidus-004 | CLI/TUI | TypeScript (commander + ink) | queued |
| liquidus-005 | MCP server | TBD from CLI-team feedback | queued |
Builds happen strictly in order — liquidus-00(n+1) does not start until liquidus-00n’s feedback has been folded back into spec.org and the spec version has been bumped.
| Version | Trigger | Classification | Date |
|---|---|---|---|
| v0 | Initial hand-authored spec | (initial) | 2026-07-01 |
| v1.0 | liquidus-001 (mocking) feedback | MAJOR | 2026-07-01 |
| v1.1 | liquidus-002 (Python) feedback | MINOR | 2026-07-01 |
| v1.2 | liquidus-003 (Go) feedback | MINOR | 2026-07-01 |
| v1.3 | liquidus-004 (TypeScript) feedback | MINOR | 2026-07-01 |
| v1.4 | liquidus-005 (MCP) feedback | MINOR | 2026-07-01 |
| v1.5 | liquidus-006 (Ruby CLI/TUI) feedback | MINOR | 2026-07-01 |
| v1.6 | liquidus-007 (Ruby SDK) feedback | MINOR | 2026-07-01 |
| v1.7 | liquidus-008 (Rack shim) feedback | MINOR | 2026-07-01 |
| v1.8 | CLI UX audit + demo-mock exception | MINOR | 2026-07-01 |
| v1.9 | liquidus-009 (Rust) + liquidus-010 (Zig) | MINOR | 2026-07-01 |
| v1.10 | -e, --example <key> (Prism Prefer) | MINOR | 2026-07-01 |
| v1.11 | SPREE_URL~/~SPREE_TOKEN canonicalized | MINOR | 2026-07-01 |
| v1.12 | Live-Solidus auth-scheme truth table | MINOR | 2026-07-01 |
| v1.13 | Path convention (.json for Rails classic) | MINOR | 2026-07-01 |
| v1.14 | Content-type parsing rule (supersedes v1.13) | MINOR | 2026-07-01 |
| v1.15 | Base-URL path resolution (primary bug) | MINOR | 2026-07-01 |
v1.9 closes the extended cycle: 10 build repos across 6 languages (JS, Python, Go, TS, Ruby, Rust, Zig) and 3 surface types (CLI, TUI, MCP server, SDK, Rack middleware). Every revision traces to a specific FEEDBACK.md observation. One major bump (v0 → v1.0) — the reified OAS was v1 classic, not v2 storefront/platform as v0 assumed. Everything after has been additive.
spec.org— start with §Provenance, then §The actual constraint, then §Grind units.CLAUDE.md— required reading before any change to any file in any of these repos.