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

WordEntry and GlossaryEntry

explain asks each unit to define the words its names spell, split as codegraph vocabulary splits them; short words and keywords are not asked. The words are given, never chosen: on receipt an entry for a word the prompt did not list is dropped, a word given twice keeps its first entry, and in is restated from the split. A record explained under prompt 1, and a templated one, has no words.

A module is shown what its types said of the words they spell, heaviest first, cut at --terms N (default 60), and reconciles them:

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.

One exception, by version: words and glossary arrived with prompt 2, so a record may lack them — one explained under prompt 1 decodes and re-encodes to its own bytes — while an answer may not: the schema sent to the provider requires them, and an answer without them is asked again, then recorded as a failure.

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 words its prompt asked to define (and a module’s glossary words), 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, no words 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.