What we need
A documentation pass covering three related areas added across the current release.
Aliases on relationships
Document the alias attribute on AssignmentRelationship and Relationship — what it is, who sets it, and why it is stable. Explain the "baby name" semantics: an alias is given to a slot before or when the target is bound, and survives the relationship's lifetime. Note the identity constraints ([:target_id, :alias] on AssignmentRelationship, [:source_id, :alias] on Relationship). Briefly signal the connection to the first-order expectation system (#74) without going into full detail.
inherited_place and inherited_party DSL
Document the inherited_place and inherited_party entities in places do / parties do. Cover the single-hop default, the multi-hop via: list, and the source_role: option. Include an example showing a service inheriting a place from an assigned resource. Explain why there is no PlaceRef or PartyRef created — the calculation IS the reference.
Field calculation modules
Document the three calculation modules once implemented (#156, #157, #158):
FieldFromAssignment — field from an AssignmentRelationship record by aliasFieldViaAssignedRelationship — field from the source instance via assignment alias traversalFieldViaAliasedRelationship — field from the target instance via aliased relationship traversal
For each: what it does, the available opts, a short usage example, and when to reach for it over the others.
Agent guidance
Update AGENTS.md with common mistakes and patterns for the new DSL entities and calculation modules. Update usage-rules.md with consumer-facing rules covering alias semantics, inherited DSL usage, and when to reach for each field calculation.
Livebooks
Update relevant livebooks to demonstrate the alias and traversal patterns with working examples.
Why it matters
These three areas work together as a system — aliases enable the traversal, inherited DSL entities and field calculations consume it. Without documentation they are discoverable only by reading the implementation. The alias concept is non-obvious without the expectation system context to frame it, and consumer-facing usage rules ensure downstream users of the framework get it right without reading source.
What we need
A documentation pass covering three related areas added across the current release.
Aliases on relationships
Document the
aliasattribute onAssignmentRelationshipandRelationship— what it is, who sets it, and why it is stable. Explain the "baby name" semantics: an alias is given to a slot before or when the target is bound, and survives the relationship's lifetime. Note the identity constraints ([:target_id, :alias]onAssignmentRelationship,[:source_id, :alias]onRelationship). Briefly signal the connection to the first-order expectation system (#74) without going into full detail.inherited_place and inherited_party DSL
Document the
inherited_placeandinherited_partyentities inplaces do/parties do. Cover the single-hop default, the multi-hopvia:list, and thesource_role:option. Include an example showing a service inheriting a place from an assigned resource. Explain why there is no PlaceRef or PartyRef created — the calculation IS the reference.Field calculation modules
Document the three calculation modules once implemented (#156, #157, #158):
FieldFromAssignment— field from anAssignmentRelationshiprecord by aliasFieldViaAssignedRelationship— field from the source instance via assignment alias traversalFieldViaAliasedRelationship— field from the target instance via aliased relationship traversalFor each: what it does, the available opts, a short usage example, and when to reach for it over the others.
Agent guidance
Update
AGENTS.mdwith common mistakes and patterns for the new DSL entities and calculation modules. Updateusage-rules.mdwith consumer-facing rules covering alias semantics, inherited DSL usage, and when to reach for each field calculation.Livebooks
Update relevant livebooks to demonstrate the alias and traversal patterns with working examples.
Why it matters
These three areas work together as a system — aliases enable the traversal, inherited DSL entities and field calculations consume it. Without documentation they are discoverable only by reading the implementation. The alias concept is non-obvious without the expectation system context to frame it, and consumer-facing usage rules ensure downstream users of the framework get it right without reading source.