Module recommendation 

The recommendation object (OMS 0x0C), the deterministic summary renderer, the dedup key, and the lifecycle state machine + audit records.

Invariants enforced here:

• Analyzers emit a (template_id, args) summary, never free prose.
• dedup_key, origin, and the params snapshot are engine-stamped.
• dedup_key excludes proposal content and the /major version, so a growing cluster or an analyzer upgrade does not re-propose as novel — for ANALYZER findings. An authored (origin = llm) executable proposal keys on a fingerprint of its content as well, because there the content IS the finding: two different lessons on one entity are two findings, and the same lesson re-authored is one.
• Lifecycle transitions are gated; pending → applied is policy-only.

Structs

AuditRecord

One immutable audit Observation per transition, hash-chained per recommendation.

CostRead

What a checkpoint read of the policy’s cost bound, beside the quality verdict. status is within, breached, or not_measurable (the field was absent or malformed on either run — then baseline/current carry whichever side did measure, or nothing). Present on a record only when the policy set a bound.

GatingEvidence

The recorded evalset-run edge (§7.4): what an apply of a code revision must present, and what its audit Observation carries. “Trust me, it passed” is not an edge; (evalset, run, stats) is.

MetricSnapshot

A reproducible metric snapshot; powers outcome review.

NearDuplicate

A stored recommendation. hash (the content address) and status (the index-layer cache) are set by the engine, not serialized into the grain body — the body is immutable content, the lifecycle lives in the state index and the audit chain. One live lesson an authored lesson restates. method is cosine (the substrate’s embedder, T1) or jaccard (normalized token sets, the T0 floor — weak, and honest about it).

OutcomeResult

A measured outcome for an applied recommendation at one checkpoint — the Verify gate’s output. held = the metric did not regress at this horizon; regressed = it got worse (a revert is proposed). A recommendation accumulates one of these per horizon, forming a time series.

RecDraft

What an analyzer emits. dedup_key, origin, and the params snapshot are not here — the engine stamps them. Non-exhaustive so the engine can add fields without breaking analyzers.

Recommendation

Summary

A deterministic, template-rendered summary. The analyzer chooses a template_id and supplies args; the text is produced here, so an analyzer can never emit arbitrary prose into the queue.

Enums

Checkpoint

When an applied recommendation is re-measured — one checkpoint of the Verify gate’s schedule, in the unit the deployment actually counts in.

ObserverType

Who/what performed a transition.

Proposal

The proposed change. Exactly one variant per recommendation.

RecStatus

Lifecycle status — a rebuildable index-layer cache (the recommendation’s content hash is stable for its whole life).

Constants

MAX_BECAUSE

Maximum length of a BECAUSE reason.

MAX_EVIDENCE

Maximum representative evidence hashes carried inline (proposal §7.1).

Functions

authored_dedup_key

The dedup key of an AUTHORED executable proposal: dedup_key plus a fingerprint of the proposal’s content. An analyzer finding is “this target has this kind of problem”, so content is rightly excluded; an authored lesson is “do this”, and two different lessons on the same entity must both reach the queue while the same lesson re-authored must not. The fingerprint is over the normalized text — case-folded, non- alphanumerics dropped, whitespace collapsed — so a rewording that changes no word is the same lesson and one that changes a word is a new one (a semantic near-duplicate is the reviewer’s call, not this key’s).

content_fingerprint

Sixteen hex chars of FNV-1a (64-bit) over the normalized content. A dedup key needs stability and spread, not cryptographic strength — a collision here would merge two findings in a review queue, never grant anything — so this stays dependency-free, as the crate is by policy.

dedup_key

Compute the dedup key: family ⟂ target_ref ⟂ action_kind, case-folded. Excludes proposal content and evidence by construction.

is_regression

The one regression rule.

revert_dedup_key

The dedup key of a REVERT: dedup_key plus the hash of the applied recommendation it retracts. An analyzer finding is “this target has this kind of problem”, so two findings on one target rightly collapse — but a revert is about one specific applied recommendation, and two lessons on the same entity that both regressed need two reverts. Until 2026-09-06 they shared a key and the second was dropped as a duplicate of the first (crates/areev-bench/CURVE.md, seed 3: two regressed, one revert).

validate_code_rules

Rule E1’s structural checks (§7.4), applied when a draft is stamped and re-checked when a stored grain is loaded (a hand-authored grain must not bypass the rule):