Docs unclear: how does `_inheritrights` behave when an entity has multiple `_parent` values?

[mitselek]

Summary

The docs cover multi-parent (entity can have multiple _parent values) and rights inheritance (_inheritrights: true inherits from parent) as separate concepts, but never explicitly say how they combine. The single most important detail — what happens when an entity has multiple parents AND _inheritrights: true — is left to the reader to assume.

What the docs currently say

From overview/entities:

Multiple parents — An entity can have more than one parent and appears as a child in each context without being duplicated.

Rights inheritance — When _inheritrights: true is set on a child entity, it inherits the access rights from its parent. Changes at the parent level cascade down to all children with inheritance enabled.

Right evaluation order: explicit rights on the entity → inherited rights from parent → _sharing level. _noaccess overrides all other rights on the same entity — including direct positive rights. It is not propagated to children via _inheritrights; only _viewer, _expander, _editor, and _owner are inherited.

The wording "its parent" (singular) doesn't address the multi-parent case.

What's ambiguous

When entity C has _parent: [A, B] and _inheritrights: true:

1. Are the inherited rights the union of A's and B's grant lists? (i.e. anyone with _viewer on A OR _viewer on B can view C)
2. Or is one parent "primary" and the other ignored for inheritance?
3. What if A grants _viewer to user X but B has _noaccess for user X — does either rule "win," or does X end up with no access via inheritance? (The docs note that _noaccess doesn't propagate via _inheritrights, but they don't say what happens when one parent's rights would inherit and another's _noaccess would not.)
4. Does the _sharing fallback ever consider both parents (e.g., if A is _sharing: domain and B is _sharing: private)?

Why it matters

We're modeling an umbrella↔collective hierarchy in Polyphony on Entu where the design assumes union-of-parents (an umbrella admin should see members in all child collectives via multi-parent on the Organization entity). If Entu doesn't actually behave that way, the design is broken and we'd have to fall back to per-entity grants or app-level enforcement. We can verify experimentally, but the docs should answer this without requiring every user to run their own probe.

Suggested fix

Add a "Multi-parent inheritance" subsection under overview/entities → Rights Inheritance that explicitly covers:

• How inherited rights combine across multiple parents (union, primary-only, etc.)
• How _noaccess on one parent interacts with positive rights inherited from another
• How _sharing is determined when parents differ

Even a one-paragraph answer would close the gap.

[mitselek]

Empirical answers from live probes

I ran controlled probes against a dev Entu instance (api.entu.app/polyphony) to get answers to the questions in the original post. Sharing them here so the docs change can be informed by actual behavior, not just speculation.

Setup

Three entities created via the API:

• P1 — person entity (no auth, used only as a target for rights references)
• A — organization entity with _viewer: P1 set explicitly
• B — organization entity with _editor: P1 set explicitly
• C — organization entity with _parent: [A, B] and _inheritrights: true, no explicit rights for P1

Q1: Are inherited rights the union of all parents' rights?

Yes — union. C materialized both _viewer: P1 (from A) AND _editor: P1 (from B).

Q2: Are inherited rights materialized on the child, or virtual?

Materialized. C's entity record physically contains references to P1 in the appropriate rights properties. Not computed at query time.

Q3 (bonus): Do higher rights tiers cascade to lower tiers automatically?

Yes. When I set only _editor: P1 on B, B materialized P1 in _editor, _expander, AND _viewer. When I set only _viewer: P1 on A, A only materialized _viewer. So the hierarchy _owner > _editor > _expander > _viewer is enforced as a materialization rule (higher tier writes lower tiers too), not just an evaluation rule. This is implied by the docs but I didn't see it stated as such.

Q4: Do post-creation parent rights changes propagate to existing children?

Yes, with eventual consistency. Setup: created P2 (brand-new person), A, B, C — none with P2 rights. Confirmed C had no P2. Then added _owner: P2 to A. Re-read C:

Time after parent change	P2 visible in C's rights?
T+0 (immediate)	No
T+3s	Yes — in _owner, _editor, _expander, _viewer (the full cascade)

So parent rights changes DO re-propagate to children with _inheritrights: true, but the propagation is not synchronous. App code that reads a child immediately after changing a parent's rights can race.

Suggested doc additions

Building on the original issue's suggestion of a "Multi-parent inheritance" subsection, the following points seem worth covering explicitly:

1. Union semantics — "When _inheritrights: true and an entity has multiple parents, the child's effective rights are the union of all parents' rights at each tier."
2. Materialization — "Inherited rights are physically written onto the child entity, not computed at query time. They appear in GET /entity/{id} responses as if set directly."
3. Tier cascade — "Setting a higher-tier right also materializes the corresponding lower-tier rights on the same entity. Setting _editor: X produces _editor: X + _expander: X + _viewer: X."
4. Eventual consistency — "Rights propagation from parent to child is not synchronous. Allow a few seconds for changes to propagate before relying on the new state."
5. (Still open) _noaccess + multi-parent — I didn't probe this since we're not using _noaccess in our design. Worth covering separately: when one parent has _noaccess: X and another has _viewer: X, does the docs' "_noaccess overrides" rule apply across parents or only within a single entity?

Happy to add more probes (e.g., _noaccess interactions, deeper multi-parent chains) if useful — let me know.

[mitselek]

Follow-up: transitive inheritance timing through deep chains

The earlier comment confirmed Q1–Q4 for a 1-level parent → child chain. A reviewer asked about deeper chains. Ran one more probe.

Setup

5-level chain T1 → T2 → T3 → T4 → T5, all entities of the same custom type with _inheritrights: true. Fresh person P with no rights anywhere. Added _owner: P to T1, polled every ~1 second to see when P appears at each level.

Results

Level	Time to first see P in _owner
T1 (the change point)	0.6s
T2 (1 level down)	2.1s
T3 (2 levels down)	3.6s
T4 (3 levels down)	5.6s
T5 (4 levels down)	9.0s

Findings

1. Transitive inheritance works without any manual touch / re-aggregation / explicit propagation call. Set the rights at the top, the cascade reaches arbitrary depth on its own.
2. Propagation is sequential per level — each child needs its parent's rights to materialize before its own re-evaluation kicks in. Per-level delta is ~1.5–3.5s and grows slightly with depth.
3. Implication for designers: write-then-immediately-read-on-deep-descendant flows can race. Design either with eventual consistency in mind (UI loading states, retry/poll) or write rights directly at each level if instant visibility is critical (defeats the inheritance simplicity though).

Suggested doc addition

Under the eventual-consistency note I suggested earlier, add a line about deep-chain timing:

Propagation through a chain of _inheritrights: true entities is sequential per level, with roughly 1.5–3.5 seconds added per level. A grant at the root of a 4-level chain takes around 9 seconds to fully reach the leaf. Plan accordingly when designing flows that grant rights at a parent and read at a descendant.

[mitselek]

Follow-up: rights entries have an undocumented inherited: true discriminator

While exploring how to query "who has been explicitly granted _editor on this entity" (vs. those who inherited it from a parent), I discovered a property field that doesn't appear in the docs but solves the problem cleanly.

What I found

Each rights-property entry (_owner / _editor / _expander / _viewer) returned by the API can carry an inherited: true field. Explicit grants don't have it; inherited grants do.

Example: an entity L with _parent: O and _inheritrights: true, where O._editor includes person P. Reading L:

{
  "_id": "...",
  "_editor": [
    {
      "_id": "...",
      "reference": "<P>",
      "property_type": "_editor",
      "entity_type": "person",
      "inherited": true       ← inherited from O
    }
  ]
}

When _editor: P is then also added directly on L, the two entries merge — the result is a single entry for P, with no inherited flag (explicit wins):

{
  "_editor": [
    {
      "_id": "...",
      "reference": "<P>",
      "property_type": "_editor",
      "entity_type": "person"
      // no `inherited` field — this is the explicit grant
    }
  ]
}

Why this matters

This field is load-bearing for any application that needs to distinguish "who has direct control of this entity" from "who has access via cascade from an ancestor." Concrete use cases:

• Computing a "contact librarian" / "responsible owner" for an entity by filtering to explicit _editor only
• UI showing "this person inherits access" vs. "this person is explicitly granted"
• Auditing tools — "who has been directly given rights to X" is a meaningful security question
• Sync logic that should clean up explicit grants while leaving inherited ones alone

Without this discriminator, every consumer would have to walk the parent chain themselves to figure it out — and they'd often get it wrong.

Suggested doc change

Under API → Properties → Example: Entity with Properties, or in a new "Inherited rights" subsection of overview/entities → Rights Inheritance, add:

Rights properties (_owner, _editor, _expander, _viewer) returned by the API may carry an inherited: true field. This indicates the entry was materialized from a parent entity via _inheritrights, rather than set explicitly on this entity. Explicit grants do not carry the field; if a person is granted both explicitly on the entity AND inherited from a parent, the entries merge into a single explicit entry (the inherited flag is dropped).

Filtering by inherited != true is the canonical way to retrieve only directly-granted rights — useful for audit, UI display of explicit vs. cascaded access, and any application that needs to distinguish "who manages this entity directly" from "who happens to have access via cascade."

Empirical setup that surfaced this

Probe entities of a custom type chained as O (parent) → L (child, _inheritrights: true). Added _editor: P to O, slept 5s, read L. Saw P in L's _editor with inherited: true. Then added _editor: P explicitly to L, re-read — saw a single merged entry without the flag.

(The 5s wait matches the per-level propagation timing from the earlier comment.)