ADR-0156: immutable typed cross-entity reference contracts

[nikstern]

Summary

• Define IOA-owned immutable typed entity references and typed action parameters.
• Define reference_equals guards over incoming parameters and stored references.
• Reuse ADR-0153 canonical key hashing for optional deterministic entity identity.
• Require one pre-commit contract across HTTP, actor, trigger, composite, and optimized write paths.
• Specify finite L0/L1/composite identity verification and fix complete weak-component coverage.
• Gate hot reload on a deterministic audit of existing entities.
• Mark the already-implemented ADR-0149 and ADR-0150 decisions Accepted.

Important tradeoffs

• Typed references are scalar and set-once; mutable Git ref CAS remains separate Genesis-oriented work.
• References to newly-created targets require the existing atomic composite transaction path; fallible post-commit spawn is not existence evidence.
• Deterministic IDs use ADR-0153 hashing unchanged, avoiding a second identity format.
• Populated entity types fail activation rather than grandfathering invalid references.

Validation

• Mandatory code-quality review: PASS, zero findings.
• git diff --check: PASS.
• Public IOA examples checked for valid TOML syntax.
• Documentation-only PR; implementation tests, cargo test --workspace, clippy, formatting, DST, deployment, and Datadog proof are required in the follow-on implementation PR.

[greptile-apps]

Accepted status overstates coverage

This marks ADR-0150 Accepted and ADR-0156 calls it already shipped, while ADR-0156 also documents that the current directed-reachability planner omits upstream members such as Z in Z -> A. Readers therefore cannot distinguish the implemented gating behavior from the still-unimplemented complete weak-component coverage promised by ADR-0150.

Knowledge Base Used: Temper spec format, codegen, and verification

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/adrs/0150-composite-cross-entity-verification.md
Line: 3

Comment:
**Accepted status overstates coverage**

This marks ADR-0150 Accepted and ADR-0156 calls it already shipped, while ADR-0156 also documents that the current directed-reachability planner omits upstream members such as `Z` in `Z -> A`. Readers therefore cannot distinguish the implemented gating behavior from the still-unimplemented complete weak-component coverage promised by ADR-0150.

**Knowledge Base Used:** [Temper spec format, codegen, and verification](https://app.greptile.com/arni-labs/-/custom-context/knowledge-base/nerdsane/temper/-/docs/temper-spec.md)

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

Historical audit lacks source data

The activation audit requires reconstructing historical reference values to verify set-once semantics, but existing data-only creates persist only the latest state in entity_catalog and do not append an event history. For those entities the audit can inspect the current reference but cannot determine whether it was previously reassigned, so the ADR needs to define an enforceable fallback or migration rule.

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/adrs/0156-immutable-typed-cross-entity-references.md
Line: 318

Comment:
**Historical audit lacks source data**

The activation audit requires reconstructing historical reference values to verify set-once semantics, but existing data-only creates persist only the latest state in `entity_catalog` and do not append an event history. For those entities the audit can inspect the current reference but cannot determine whether it was previously reassigned, so the ADR needs to define an enforceable fallback or migration rule.

How can I resolve this? If you propose a fix, please make it concise.