hecks

Guides

Not doctested itself — an index. Every guide it points to is; see AUTHORING.md if you’re about to write one.

Each guide answers a decision you actually have to make — which field wants a value object, how a rule refuses, what a query can and cannot reach — with a real example the suite runs before you read it. If a guide is wrong, it goes red.

Start at the top if you’re new; jump straight to the one you need if you’re not.

1. Getting started — a domain declared, wired, booted, and refused, in one sitting.
2. Your own domain — write a bluebook of your own, run it, and deploy it to AWS Lambda.
3. Aggregates and value objects — identity, shape, closed sets, and the trap in nesting them.
4. Commands — everything a command may do, everything it may refuse, and the roster of refusal classes you’ll actually hit.
5. Queries and read models — what the build-time seal catches for you, and the one open question it doesn’t.
6. Lifecycles — states, transitions, and what hecks model_check flags before you ship one wrong.
7. Entities — identity and behavior that lives inside an aggregate, never addressed alone.
8. Policies and process managers — reactions, sagas, correlation, and the depth limit that keeps a feedback loop from becoming an incident.
9. Wiring — the hecksagon and the world: what’s decided where, and why persistence is never the domain’s problem.
10. Schema evolution — a shape change, and proof that the data underneath it survives. Needs a real Postgres.
11. Verification — model_check, fuzz, the corpus, and which one to reach for at which stage of actually shipping.
12. Writing an adapter — the contract a new persistence or driving adapter has to keep, walked against the smallest real one.
13. Extending hecks — adding a word to the language itself, and the conformance gates that stop it drifting from what it says.
14. Running a runtime — a second runtime exists (rust/); this is how it works and how to run or extend it: the canonical IR’s exact shape, the dispatch order, and how the expression grammar given/ensures/invariant compile down to.
15. Behaviors — hand-curated examples of how a domain is used, in its own vocabulary, run as tests: hecks operation.run_behaviors, the rspec shim, and what emits: sees through a real policy cascade.
16. Language versioning — how the bluebook surface itself carries proposed/admitted/deprecated/retired, and what hecks language_run.rename does with a rename.
17. Projections: Rust and WebAssembly — the bluebook as the one definition, projected to generated Rust and WASM, and how that output is held equal to Ruby’s.
18. AI-native development — the storehouse bus and its MCP server: one checked surface an agent works through, and what its identity check does not do.
19. Project status — what works today, what is experimental or partial, and where the gaps are written down.

Beyond the guides

• The DSL reference — one page per context, one runnable example per word.
• Architecture map — the lib/hecks/ and rust/ directory layout, and the dependency direction the split follows.
• The commands — every hecks <verb>, with the bin/ script it replaces.
• Running a rules service — from a bluebook to a deployed API, with the auth caveats.
• Resolution rules — the exact algorithm behind every piece of DSL sugar that lets a bluebook omit something the runtime can derive: overview, cross-entity given.
• Decision log and implemented decisions — one document per architectural decision, kept even after superseded.
• Changelog and 1.0 readiness.
• The query DSL, command/query form, Rails integration (design only).
• docs/HECKS_IMPLEMENTATION_PLAN.md — the full aspirational architecture in one document. Treat this as a roadmap, not a status report; Project status is the status report.

This site is open source. Improve this page.