Repository navigation
Read relations between entities in both directions #2526
Copy link
Copy link
Closed
Labels
Milestone
Description
Part of #2417 (F-ENT). First slice: relations between entities, read in both directions (ENT-01, D08). Entity types are content types flagged as fact sources (#2465), and a relation is a reference field on an entity type that points at another entity: a single reference relates one entity to another, and a list of references relates it to many. So product.category is one-to-many from the category's side, and product.specs is many-to-many. Entities are stored as entries (#2491), and every reference a version makes is in the reference index (#2494). This slice reads relations from that index, outgoing and incoming.
Scope
- Core (
FluentCMS.Core.Entities):IEntityRelations, returningResult, reads an entity's relations. It lists the entities it relates to, field by field, and the entities that relate to it, with the type and field of each. A relation names both entities and their types, the field that holds it, the target field when it points at one field of the target (such asproduct.price), and whether the latest draft, the published version or both hold it. - Only entities count: both ends must be entries of entity types, so a page that references a product is a use (
IWhereUsed), not a relation. Deleted entities are left out on both ends. - Relations survive versioning: they point at entities, not versions, so a new version of the target keeps them. A new version of the source keeps or drops each one with its field value, and the published version keeps its own until a publish replaces it.
- Reads come from the reference index, never from the stored documents (ADR-0005), in a fixed number of queries whatever the number of relations.
- Scope (MCP-05): an agent reads relations only of an entity of a type it may read, and only sees related entities of types it may read.
Out of scope
- Refusing references from entity types to plain content types in the schema. That is a schema rule for F-SCH, and SCH-05 is changing that code now.
- Cardinality limits beyond what the field shape gives, and inverse names in the schema document.
- The relate tool: with the entity tools, the last F-ENT slice.
- Unsourced and stale flags, and the blast radius: later F-ENT slices.
Acceptance
- In the reference model, a product's relations list its category and its specs, outgoing; the category's list the product, and the spec's list the product, incoming.
- A relation held only by the published version, or only by the latest draft, is reported with that flag. Updating the category entity keeps the relation, and updating the product without the category drops it from the latest draft only.
- A page that references the product is not a relation of the product, and a deleted entity appears on neither side.
- An unknown entry or an entry that is not an entity fails with its own code; an agent outside its scope is refused, and related entities of types outside its scope are left out.
- Everything above passes on SQLite and PostgreSQL, with no migration and no new package.
Activity
Read relations between entities in both directions (#2528)