Relationships

A relationship is a first-class stored link: its own id, an optional label, an optional type, tags, and a snapshot of the target's version and revision when it was made. A Rich Live Link is how a relationship appears in a document; the relationship is the data.

Single and list relationships

Both live in one table.

• Single: one row with from, to, label, type and the version snapshot.
• List: a header row (label, type, tags, no to) plus member rows, each with parent_id, its own to, a position and its own snapshot. "Why? Guilt, new ideas, perfectionism" is one list of three.

The same pair of entities can be linked more than once, with different labels.

Labels

A label is optional free text that says what the target answers from the source's point of view: "Am I lying to myself?", "Why?". The author decides whether a link has one. A labeled link always renders as a minimal link (see Rich Live Link).

Types: references and associations

A link points from the dependent entity to what it relies on. A plan built from a PRD links plan derived-from PRD.

• A reference derives meaning from its target. It goes stale when the target changes, and it blocks the target's delete.
• An association only connects. It never goes stale and never blocks anything.
• An untyped link is a reference.

Starter vocabulary (MVP), each with an inverse name for backlinks:

User-defined types are post-MVP. Types and tags can be deprecated: existing uses stay, new ones are refused. A type in use can't be deleted.

Cycles

References may never form a cycle; associations may. With no reference cycles, the delete rule never deadlocks.

• The link picker greys out entities that already reach the source through references, with "would create a loop".
• The server checks again on create, under a per-user lock, because bots and the API don't use the picker. A refused link names the chain and suggests an association.
• How the lookup scales (recursive query, depth cap or closure table) is for system design.

So two entities never reference each other, directly or through others. When both want to talk about one dependency, they mention the same relationship (see Mentions) instead of adding a reverse reference.

Mentions

A doc that explains why project X started (A) and the doc about project X (B) share one dependency: B is explained-by A. Both want to point at it, several times. That is still one relationship.

• A mention is a mark in an entity's content carrying one relationship id. A relationship can have any number of mentions, in its source and in its target. A may mention it three times and B once.
• Mentions in the target read with the inverse name: in A it reads "explains", in B "explained by".
• Staleness, the delete block and the cycle check follow the stored direction only. B sees a dot when A changes. A's mentions of B never go stale.
• Unlinking, or removing the source's last mention, deletes the relationship. Removing the target's mentions never does; they are only a view of it.
• When the relationship goes, the target's mentions show No longer linked. The text stays, the link is disabled, and the copy is neutral, because B may have been deleted or simply stopped linking. Core never edits A or bumps its counters. A's author dismisses the mention (the smart link goes, the plain text stays) or relinks it.
• The deleted relationship is a tombstone (soft delete with actor and reason). Undo, or restoring a deleted B, brings back the same relationship and A's mentions come back with it. Linking the pair again later creates a new relationship with a fresh snapshot; A's author is offered "relink" to point old mentions at it.

Anchored links

• Source anchors. A user selects text (a word, a sentence, a paragraph) and links it. The anchor lives in the source's content as a mark carrying one relationship id (a mention). A mark carries one link and marks don't overlap, but one link can have many marks. The selected text is the label.
• Target anchors. A link can point at part of its target, stored on the relationship as to_anchor. Blocks (a paragraph, heading or list item, by a stable block id) come first. Word and sentence anchors are in the MVP; how they survive edits is for system design.
• Staleness stays per entity, never per block.
• Unlinking, or deleting the source's last anchored mention, removes the relationship, whoever does it.
• A referenced passage is protected like a referenced entity. The editor marks passages that have incoming references. Deleting one stops and offers three choices:
  • Keep the passage.
  • Save as a new version. The passage goes, with an optional change note. Referencers get the red dot, and their link shows "passage removed" until its author re-anchors it, points it at the whole entity, or unlinks.
  • Supersede. The edit becomes a new entity; the old one keeps the passage intact.
• Editing a referenced passage asks "3 links rely on this passage. Is this a new version?" The author decides whether it is a rephrase (revision) or a change in meaning (version).
• Core checks every save, autosave included: a save that removes a referenced passage is refused with passage_referenced and the list, unless it is a new version. The editor catches it first; the server is the backstop for bots and the API, as with cycles. The check costs the size of the change, not of the document, so it stays fast at autosave rates.
• Associations into a passage don't protect it. Deleting the passage deletes them; the source's leftover mark renders as plain text, and core bumps the source's revision (actor: system, with the reason), never its version.

Disabled modules

A relationship into a module the user no longer has stays, and renders locked. While locked nothing changes on its own. The user may unlink from the side they can open, which is permanent. No new links into a module the account doesn't have; the API refuses too.