Reusable cross-world projection calculation.

Replaces typed belongs_to for cross-resource references where the target's concrete subtype isn't known at the source resource's compile time. The calc resolves the target to its outermost concrete world at read time via AshNeo4j.worlds/1 — late-binding by design, open-world by construction.

Used by Diffo.Provider.PlaceRef and Diffo.Provider.PartyRef to replace their belongs_to relationships pointing at the generic Place/Party/Instance abstract readers. Also usable directly on consumer leaves that want to point at any subtype across the cascade (e.g. BaseGeographicSite.address → GeographicAddress or consumer-domain Address leaf).

Usage

calculate :place, :struct,
  {Diffo.Provider.Calculations.ProjectedRef,
   [id_field: :place_id, reader: Diffo.Provider.Place]}

Options

• :id_field (atom, required) — the attribute on the calculated record that holds the target's id.
• :reader (module, required) — the abstract reader resource for the target type. Lets the calc do a bootstrap Ash.get to load the target node so AshNeo4j.worlds/1 can project it to its outermost concrete world. For diffo built-ins: Diffo.Provider.Place, Diffo.Provider.Party, Diffo.Provider.Instance — each kept in core minimally for this role.

Result per input record

• nil — the source record's id_field is nil (legitimate absence; no ref to project).
• concrete struct — the outermost concrete world's resource, loaded with all subtype-specific attributes.
• %Diffo.Unknown{} — id_field is set but the target couldn't be projected (see reason vocabulary).

Plus the standard %Ash.NotLoaded{} until the calc is loaded.

Reason vocabulary (local to the calling record's world)

• :no_target — bootstrap Ash.get failed; target id doesn't exist in the graph. Context carries %{id_field: atom, target_id: id, reader: module}.
• :no_concrete_world — bootstrap loaded but AshNeo4j.worlds/1 returned []. Context carries %{id_field: atom, target_id: id}.
• :projection_failed — projection identified a concrete world but its Ash.get failed. Rare; indicates a Neo4j label / Ash resource mismatch. Context carries %{id_field: atom, target_id: id, resource: module}.

Per the Cross-domain lookups AGENTS.md section, reasons are world-local — consumers in other worlds should treat them as opaque and (if composing) wrap via :inner_unknown.

:world stamping

Each %Diffo.Unknown{} is stamped with record.__struct__ — the consumer's concrete resource (e.g. Diffo.Provider.PlaceRef or MyApp.SomeRef). No transformer injection needed because the calc runs per-record at runtime and the consumer's resource is directly available from the record.