References and backlinks

A reference is a citation from one document to another, written as a docref annotation on a passage of text. Both directions of the graph it builds are queryable: the documents this one cites, and the documents that cite this one.

A link to a specific block also works outside a docref: the document address with ?blockKey=<key> opens the document, scrolls to that block and previews it on hover, so a pointer to a tracker item or a ruling lands the reader on the right section instead of the top of the page. When you point a reader at one section, paragraph, decision, tracker entry or question, in a chat, a report, a pull request or a plain link, use that block link, https://oddlynew.com/d/<document id>?blockKey=<key>, with the key from getDocument with scope { type: "outline" }; the plain address is for the document as a whole. The link is stable: a block keeps its key across edits and versions, and new keys appear only when a document is created or copied, so the link keeps landing on its block until that block is deleted, after which the document opens at its start. A docref may also point at a block of its own document. That is a jump within the document, not a reference: it is stored without a version pin and never appears in backlinks, outgoing citations, drift or reference counts.

Reading both directions

Reading a document with the orientation scope returns both sides at once, bounded by outgoingLimit and backlinkLimit. That is the cheap way to see how a document sits in the graph.

When you want the incoming side properly, getBacklinks({ documentId }) pages through it: 20 entries by default, 50 at most, with an opaque cursor for the next page.

Asking for backlinks is cheap

Every docref is stored as a row in a link graph, written in the same transaction as the document version that contains it. Asking which documents cite a given document is an indexed lookup on that graph. It is not a search, and it does not walk the organization's documents looking for matches.

The cost tracks the number of citations on the page you asked for, not the size of the organization. Query backlinks whenever they would tell you something.

Content stays authoritative. The graph is derived from it, and every row can be rebuilt by reading the source document again.

An edge is a place, not a pair

A backlink does not say "document A links to document B". It identifies the exact annotation: the source document, the block, and the mark within that block. Two citations of the same target from the same source are two separate entries, because they are two separate claims.

Each entry carries enough to judge it without opening the source. sourceDocumentId, blockKey, and markKey identify one citation occurrence: blockKey is the source block, while markKey is the exact annotation within that block. targetBlockKey addresses the cited block in the target and is not interchangeable with either source key. anchorText gives the visible words the citation was written on; sourceTitle and sourceTypeFamily describe its document.

Backlinks follow the persisted document

The graph updates when a document's persisted head flushes, not at the moment of an edit. A citation you just wrote appears once that version settles. This is deliberate: backlink readers and search readers see the same persisted snapshot, instead of diverging from newer live edits.

If a reference you just added is not in the graph yet, it is not lost. It is not yet flushed.

Drift tells you which citations still hold

A reference can pin the target version and target block it was written against. targetDrift on every outgoing citation returned by getDocument and every backlink entry reports whether that pin still describes reality. Beyond current, it distinguishes a changed target document, a changed or deleted target block, a missing target version, a target that was deleted, retracted, removed, or unreadable, an unpinned reference, pending convergence, and the case where drift cannot be determined. On getDocument citations, driftBasis makes the evidence explicit: target_state for target lifecycle or readability, version_pin for a version-pinned comparison, live_receipt for receipt-based comparison of an unversioned live citation, and insufficient when the resolver lacks enough evidence. Raw checksums and block hashes stay internal.

Use drift to decide what kind of attention a citation needs. When target_document_changed carries a targetBlockKey, the target document moved but the cited block is unchanged. Keep the original pin as evidence and do not edit or re-pin the source merely to make this informational status disappear. When targetBlockKey is null, the legacy citation covers the whole document, so a changed document still requires review. target_block_changed is also a review candidate: reread the cited block and judge whether the claim still holds. A deleted block, missing pinned version, deleted target, retracted target, or removed target needs repair. pending_convergence, unpinned, and indeterminate describe incomplete evidence or coverage; do not treat them as proof that the citation is wrong.

orientation.outline[].needsReviewCitationCount follows this attention taxonomy: it counts review and repair findings, including a changed legacy whole-document citation, but excludes informational block-scoped document changes and coverage states. orientation.citationHealth.*.byStatus remains the raw status distribution, so those totals can be higher without implying more required work.

Circular references and convergence

References may be circular, and Oddlynew can read and query those graphs like any other. What it does not guarantee is convergence when every version pin in a cycle is repeatedly advanced to the other document's latest version: changing one source creates a new source version, which can make the opposite pin older again. This is an intentional boundary of immutable versions plus pins embedded in versioned content, not a graph error. Treat a pin as evidence of the version reviewed when the source was written. Re-pin only after a relevant change has been judged and the source should adopt it; do not chase head versions merely to clear drift. Block-scoped drift keeps unrelated document changes informational, but a cycle whose cited blocks genuinely change can still require judgment and may have no stable state in which every pin is latest.

References cross organizations

A docref can point at a document in any organization — public or private. Creating the reference requires that you can read the target at that moment; from then on the reference is part of the source document like any other content. Every reader of the source sees the reference and its state: which document it points at, the pinned version, and whether the target has moved on. The target's content — title, text, search results, backlinks — resolves only for readers who can themselves read the target. Citing never discloses anything the cited organization has not shared with you.

This is what makes building on someone else's knowledge simple. When you have access to another organization's knowledge — a partner's research, a client's context, a collaborator's notes — you can build your own documents on top of it by citing it directly: no copying, no widening of who can read the original. The same primitive is the foundation for knowledge sharing between organizations, and for what can grow out of that.

Backlinks also obey the reader. A citation living in a document you are not allowed to read does not appear in your results.