luria

A remote constructs per scheme: dir, document + anchor, or url

4 min read

Graph View

ADR-023: A remote constructs per scheme: dir, document + anchor, or url

Status Active · Filed 2026-08-04 · Issue #6 · Influenced by ADR-016 · ADR-022 · Influenced ADR-024

Context

A remote was one directory of code-named files: [luria.remotes.SG] carried a single dir and optional url template, and every composed code constructed into the same place. Right for SG-ADR-*; wrong for SG-DP-*, whose documents are sections of a document-rendered page — the construction produced a confident URL to a file that has never existed, which is the exact failure ADR-016’s “discovery is authoritative” rule answers on the lockfile rung but not on the code-only rung.

ADR-022 scoped the url-ok escape hatch and predicted this decision: each acknowledgement’s reason describes a gap in what remote config can express, and a recurring shape is the cue to grow the config. The first accumulated reason was exactly this shape — “strata-g’s principles are sections of one document.” Strata-g is a Luria project on a legacy layout; the gap was never about foreignness.

Decision

A remote’s schemes construct independently. Each entry names one shape:

[luria.remotes.SG.schemes.ADR]
dir = "docs/decisions"                  # file per code (today's behavior)

[luria.remotes.SG.schemes.DP]
document = "docs/design-principles.md"  # sections of one page…
anchor = "dp-{number}"                  # …at these anchors

[luria.remotes.X.schemes.RFC]
url = "https://x.example/rfcs/{number}" # full template, overrides both

Per-scheme config wins over the remote-level dir/url, which keep serving every unconfigured prefix — so an existing remote’s behavior is unchanged until a scheme entry says otherwise.

Three details that are load-bearing:

  • The anchor template defaults to the stable-anchor shape — the prefix lowercased plus the unpadded number, dp-18. That is what Luria’s own document render emits (the <a name="dp-N"> anchors exist precisely so they can be addressed from outside), so a remote on current conventions needs only the document line.
  • The lockfile’s authority stays scoped to files. Discovery reads directory listings; a section of a document never appears in one, so a document-scheme code absent from the lockfile is not evidence of absence. An anchor or url construction never consults the lockfile; file-per-code construction remains under its authority (ADR-016).
  • The remote-level dir default moves to record/decisions.d, following the read/write boundary (ADR-021) — the defaults are Luria’s own conventions, and the conventions moved.

The url-ok loop closes as ADR-022 designed: a hand URL the new construction now covers becomes fixable — delete it, let the citation construct, and the leftover acknowledgement reports itself stale. The residue keeps its annotation with a narrower reason: strata-g’s DP citation now constructs to the right document, and the url-ok excuses only the legacy heading-derived anchor that no template can compute.

Alternatives considered

  • Zero-config prefix magic — a built-in default mapping DP codes to docs/design-principles.md#dp-N with no scheme entry at all. Rejected on the rule that runs through this whole subsystem: a default is a guess about the remote, and explicit config is a claim by the user. The guess is confidently wrong for exactly the remote in front of us — strata-g’s legacy anchors are heading-derived, so the constructed anchor would land silently at the top of the page. One document line is the honest price.
  • Anchor discovery — fetch the remote’s assembled document and read the real anchors into the lockfile. Puts the network in the resolution path for a case where it cannot help: the remote that needs it most is private, and a public remote on current conventions doesn’t need discovery at all. If a public legacy remote ever matters, this can become a fourth rung; nothing here forecloses it.
  • Hand-maintained lockfile entries for sections — the same fact as a url-ok’d hand URL, moved into JSON where the reason for it can’t travel alongside. The directive keeps the fact where it is used and visibly acknowledged; centralizing it would trade the visibility for nothing.
  • Status quo — every document-rendered citation stays a url-ok’d hand URL. Workable, but the acknowledgements were already accumulating one shape, and ADR-022 says that accumulation is a feature request, not a filing cabinet.

Consequences

  • SG-DP-18 constructs to …/docs/design-principles.md#dp-18 — the right file, the wrong legacy anchor — and the citation in DP-9 keeps its url-ok with the narrower reason. LU gains the same scheme entry as dogfood the network check can actually verify.
  • luria remotes labels the construction it used per code — “a document anchor, per the scheme” — so the report says which rung answered (DP-1).
  • --check HEADs the document URL; the anchor itself is not HEAD-verifiable, and claiming otherwise would be a lie of precision. Fetching page content to verify anchors is possible future work, same trade as anchor discovery.
  • A remote with both a scheme entry and a lockfile resolves each code by the right authority — anchors from config, filenames from discovery — which is the first time the two rungs coexist inside one remote.

Backlinks