insights.jsonl

The side-car explain writes: one explanation record per operation, type and module, in the vocabulary of the Specy domain metamodel. It lives beside the model — <model>.insights.jsonl by default — and never inside it, so it can be regenerated, pointed at another model, or deleted without touching model.jsonl or model.db.

File layout

header → i* → f* → eof

f lines are the units a run asked for and could not explain; a side-car with none has no f line. A reader that only wants explanations keeps the t:"i" lines.

Records are sorted by (level, id), with operation before type before module, and are re-serialized through their Zod schema, so a record built in memory and one read back from disk are the same bytes. The body carries no timestamp; only the trailer does. Two runs with the same records are therefore diffable: what changed is what was re-explained.

During a run, finished records are appended one per line to <out>.journal and the sorted side-car is rewritten from base plus journal at each layer boundary, so an interrupted run resumes where it stopped. Reading a journal is lenient (its last line may be cut); reading the side-car proper is strict.

header

i — one insight record

f — one failure record

A unit left without an insight record, and why. It exists exactly as long as the gap: a run that explains the unit drops it, a run that fails again replaces it with attempts + 1, a run that did not attempt the unit (--scope, --max-calls) carries it over. explain --retry-failed takes its scope from these lines. Sorted like the records; no timestamp.

{"t":"f","id":"java:org.broadleafcommerce.core.web.expression.checkout","key":{"lang":"java","module":"org.broadleafcommerce.core.web.expression.checkout","symbol":""},"level":"module","members":["java:org.broadleafcommerce.core.web.expression.checkout"],"model":"openai/gpt-5.6-luna","reason":{"kind":"provider","message":"This request requires more credits, or fewer max_tokens. …","status":402,"retryable":false},"attempts":1,"calls":0}

eof

Blocks

Every block carries a name — the ubiquitous-language name the model proposes — a description, and a confidence number clamped to [0,1] on receipt.

OperationBlock

TypeBlock

ModuleBlock

Vocabularies

Closed enums, restated as literals in ddd.ts with the source cited.

Strict structured output

Providers’ strict structured-output mode requires every property to be required and no additional properties, so “optional” is expressed as .nullable(), never .optional(), and no numeric or string constraints are emitted. confidence is clamped on receipt rather than constrained in the schema.

Fingerprints

Every record carries a sha256 over what it was computed from: the prompt version, the model slug, the level, the source slices, the comments, the signatures, a digest of the facts shown, the fingerprints of the units it depended on, and the ids of dependencies that had no record. Merkle-style: change one leaf’s source and exactly its transitive dependents and containers change.

The explanation text is deliberately not hashed — a non-deterministic answer must never cascade re-runs. A re-run plans reuse for every unit whose members’ records match; --force overrides. Because a missing dependency is part of the fingerprint, a dependent explained while its callee had failed or was out of scope is redone once the callee exists.

Templated records

A getter, setter, equals/hashCode/toString/compareTo, or a field-assigning constructor is described by a template with origin: "template", confidence 1 and no model call — decided from facts only: no throw site, no corpus call, cyclomatic ≤ 1, and at most one field touched. Anything with a throws fact or a corpus call is never trivial, however short.