liquidus

#+TITLE: liquidus #+SUBTITLE: Solidus API toolkit against a contract-only backend #+AUTHOR: JW #+DATE: [2026-07-01]

• What this repo is

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][§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 the liquidus-005 MCP 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.

• Demos

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 — Ruby liquidus CLI (liquidus-006), curated Solidus data.
• TUI: demos/gifs/tui.gif — Ruby liquidus-tui (liquidus-006), slash-command palette.
• MCP: demos/gifs/mcp.gif — Python liquidus-mcp (liquidus-005), F5 provenance wrapping.

• Demo mock exception :PROPERTIES: :CUSTOM_ID: demo-mock-exception :END:

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.json points at the liquidus-005 MCP server which itself points at localhost: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.

• What this repo is not

• 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.

• Where the implementation lives

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.

• Spec revisions

| 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 (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.

• Read next

• 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.