Lobster Technical Reference Manual

Describe the system in two or three sentences. Name the problem it solves, the environment it targets, and the maturity of the implementation. Link out to the concise project overview in README.md and to day-to-day status tracking (such as docs/status.md in this repository) by file path.

A second paragraph should state non-goals explicitly. What is deliberately out of scope? What should a reader not expect from this system?

The intended reader is an engineer who will build on, integrate, or verify this system. Assume fluency with the relevant domain and no prior knowledge of this project. The manual demonstrates the writing primitives used throughout:

External links look like this: the Asciidoctor documentation describes every block used in this manual. Internal cross references look like this: Verification explains how the claims in Performance are tested.

Units, notation, and naming rules used in this manual:

One paragraph per block: what it owns, what it does not own, and which invariants it upholds. Prefer ownership statements ("Block A owns …") over mechanism; mechanism belongs in Design.

The table below is the canonical block inventory. Keep it dense: one row per block, one responsibility clause per row.

Describe the end-to-end path in order. Name each handoff and the artifact it carries. A minimal equivalent in code:

Each arrow is a contract: document the artifact format at the arrow, not just the stage at either end. Where a stage can fail, name the failure signal here and defer the full taxonomy to Verification.

How is the system told what to do? Enumerate the control inputs: command-line flags, configuration files, environment variables, or control registers. State defaults and state which settings are fail-closed (an invalid setting stops the system rather than degrading silently).

Describe each stage in pipeline order. For each stage, state its input contract, its output contract, and the invariant it preserves for downstream stages. The figure below shows the generic shape; replace it with the real block diagram for this system.

Keep figures simple line diagrams with a caption. Store sources next to the manual (for example under docs/diagrams/) and export vector graphics into docs/images/.

Name each intermediate representation or data model and the passes that may observe or mutate it. State explicitly what structure must be preserved across lowering: upstream stages must not destroy information that downstream stages (synthesis, optimization, code generation) still need.

Errors are part of the design, not an appendix to it. Classify every failure the system can report:

Each class gets a code namespace that does not collide with the others, so a bare code such as E110 or TRAP-REF is unambiguous without context.

State the rules that apply to every interface table in this chapter:

One subsection per interface. The table is the contract; the prose explains only what the table cannot.

A second interface follows the same pattern. Add subsections as needed; each appears as a collapsible entry in the sidebar.

State ordering guarantees in one paragraph: what may be reordered, what may not, and which operations act as ordering barriers. Trapping or error operations are observable side effects — they are never removed, speculated, or reordered across sequence points.

The smallest complete interaction, first. No explanation before the reader has seen it work:

Follow with one paragraph per line: what each command did, what success looks like, and where the corresponding diagnostics are specified (Error handling).

Exhaustively list every knob and observable: registers, flags, configuration words, or API entry points. This is the table a driver author codes against.

Multi-step procedures as numbered lists, one step per action, with the expected observable after each step:

One paragraph per layer, from cheapest to most expensive:

Document the fail-closed rule here: any verification stage that cannot prove its invariant stops the pipeline rather than passing suspect state through.

The matrix maps claims to evidence. Keep it current: a row without evidence is a roadmap item, not a fact.

Every fixed bug gains a regression check that fails without the fix and passes with it. Checks run in continuous integration on every change; a feature is not complete because one example exercises it.

Prerequisites first: compilers, toolchains, and the minimum versions that are known to work. Then the build itself as a numbered sequence:

Every dependency is load-bearing and listed here with its purpose. There is no vendored copy of anything the package manager can pin.

Name each deliverable, where it lands, and how to tell a good one from a bad one (checksums, version stamps, self-test flags). Generated files are never committed to the source tree; they live under a clearly generated directory that the ignore rules exclude.

Report each metric with four columns: what was measured, on what, how, and the result. Point at the harness or benchmark definition rather than pasting raw logs.

When performance follows a simple law, state it. The relationship below is shown as a literal block so the manual renders identically with or without mathematics support:

To render real equations instead, uncomment the :stem: attribute in docs/index.adoc. That pulls MathJax from a CDN at page-view time, so it remains opt-in: the default manual is fully self-contained.

Numbered, each with its current workaround:

When a gap closes, delete its item and move the new capability to the chapter that owns it. This chapter must never describe the present as if it were the future.