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.

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.

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

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.

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):