# ADR 0005 — Node identity omits the default port

Status: proposed (2026-08-17)

## Context

A graph node is identified by its URL string and compared exactly: the store
looks up `s.nodes[url]` and matches backlinks with `e.To != url`, with no
normalization anywhere. Identity is therefore whatever spelling the writer
used, and two spellings of one document are two documents.

Today the intended canonical form is `mark://host:port/path` with the default
port filled in, because `fetch.ParseMarkURL` supplies `protocol.DefaultPort`
when the address omits one. That intent was never enforced. `demarkus-mcp`
rebuilt the canonical form explicitly before crawling; the CLI, TUI, and broker
passed through whatever the caller typed. PR #318 closed the crawl entry by
canonicalizing inside `graphstore.CrawlAndPersist`, using the caller's own
`parseURL` so each transport keeps its own rule.

The damage was real before that fix. A rebuild of the demarkus-soul graph
produced 388 nodes for 192 documents, 204 keyed `mark://soul.demarkus.io/...`
and 167 keyed `mark://soul.demarkus.io:6309/...`. A second symptom rode along:
`EtagFetcher` keys etags canonically while nodes were keyed raw, so `Merge`
never attached an etag from a portless crawl and every conditional re-crawl
silently degraded to a full refetch.

Three doors remain open after PR #318:

- `SeedFromExport` ingests rows from another producer's `/graph.md` verbatim.
- The read paths (`GetNode`, `Backlinks`, `BacklinksEnriched`) trust the
  caller's key. The broker's `handleMarkBacklinks` validates the URL shape and
  then queries with the agent's raw string, so a near-miss returns "no
  backlinks" rather than an error.
- `links.Resolve` returns any destination containing `://` untouched, so an
  absolute body link written without a port creates a second node even under a
  canonical crawl.

Two further facts shape the decision. The system already separates identity
from dial address: `mark_worlds` returns a world's name and its dial address as
distinct columns, and the broker addresses worlds as `mark://{worldName}/{path}`
with no port at all, rejecting a port outright as an operator typo. And humans
and agents naturally write `mark://host/doc.md`, which today is the wrong
spelling.

## Decision

**Node identity is the authority with the default port omitted.**

- `mark://host/path` when the server listens on `protocol.DefaultPort`.
- `mark://host:7000/path` when it does not. A non-default port stays part of
  identity because it names a different server.
- The broker's `mark://{worldName}/{path}` form is unchanged. It is already
  portless, so both transports now follow one rule rather than two.

### Identity is not the dial address

`fetch.ParseMarkURL` keeps filling in the default port. Dialing needs a port;
identity does not. These are separate functions with separate jobs, and
conflating them is what produced the original bug. Canonicalization for
identity gets its own exported helper, and the transport keeps its own.

### Normalize at every keyed door, not just the crawl

The store takes an injected canonicalizer, following the existing `parseURL`
pattern so the store never hardcodes a rule that is wrong for the broker.
Hardcoding "strip 6309" inside `graphstore` would rewrite `mark://servicing/x`
as `mark://servicing:6309/x` and corrupt every brokered world key.

It is applied on ingest (`Merge`, `SeedFromExport`, the crawl entry) and on
read (`GetNode`, `Backlinks`, `BacklinksEnriched`). Read-side normalization is
not redundant with ingest: a mismatch on read returns an empty result, which is
indistinguishable from a document that genuinely has no backlinks, and a silent
wrong answer is the failure mode this whole class of bug keeps producing.

### Accept both forms forever

Ingest accepts either spelling and stores the stripped one. Published graphs
written under the old rule keep parsing, and their rows are stripped on the way
in. `graph.json` bumps `schemaVersion` from 1 to 2 and strips keys on load, so
existing stores migrate instead of being rejected by the version check.

There is no flag day and no coordinated release. Hub aggregates can be
republished whenever it suits.

## Consequences

- The spelling people naturally type becomes the correct one, which closes the
  absolute-body-link hole by making the common case canonical rather than
  wrong.
- Identity matches RFC 3986 section 6.2.3, which removes a scheme's default
  port during normalization, and matches the broker's existing split between a
  world's name and its dial address.
- `/graph.md` row shape changes. Producers are the `demarkus-agent` federation
  crawler, which publishes hub aggregates, and `mark_graph_publish`. Consumers
  are the MCP seed path, the broker seed path, and the library floor, which has
  broken once before on an export format change. Accept-both keeps every one of
  them working across the transition.
- Moving a world off the default port changes the identity of every node it
  serves. This is already true and is not a regression, but it means a port
  remains load-bearing whenever it is not the default.
- Tests that pin the old rule change with it: the fedcrawl producer-consumer
  contract test, the MCP and broker seed tests, and
  `TestCrawlAndPersistCanonicalizesStartURL`, whose expectation inverts.
  `TestCrawlAndPersistKeysMatchAcrossURLForms` survives untouched, because it
  asserts that the two spellings agree rather than which one wins. That is the
  test carrying the real invariant.

## Alternatives rejected

- **Keep the port always.** Internally consistent, and it is what the current
  data already looks like. Rejected because it leaves the natural spelling
  permanently wrong, keeps two identity rules across the two transports, and
  does nothing about absolute body links.
- **Normalize on read only.** Cheaper, and it would answer queries correctly
  today. Rejected because stored data stays forked on disk, so every export and
  every seed keeps propagating both spellings.
- **Hardcode the rule inside `graphstore`.** Rejected as wrong for the broker,
  as above.
- **Reject non-canonical input.** Honest, and it surfaces the problem instead
  of hiding it. Rejected because a store seeded from another world's `/graph.md`
  cannot control what that producer wrote, and refusing to seed is worse than
  normalizing.

## Deferred

- Whether the LOOKUP catalog and the OKF export should adopt the same identity
  rule. They key by path within a world today and are unaffected.
- Case normalization of the authority. `mark://Host/x` and `mark://host/x`
  remain distinct until there is evidence anyone writes the former.