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.
• 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

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

dedup_key

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

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