# demarkus-library — Debt & Deferred Work

Technical debt and consciously deferred improvements.

## Reading-room rendering upgrades (inspired by markdownviewer.pages.dev)

Capabilities to absorb, NOT the tool (it's a client-side editor — inverse
architecture). Split along ADR 0003:

- **Server-side, zero JS (do first):** syntax highlighting via
  goldmark-highlighting/chroma; GFM alerts; emoji extension. Bluemonday
  policy must allow chroma classes/spans.
- **JS islands (tracked ADR 0003 concessions):** mermaid.js island
  (degrades to `<pre>` code block); KaTeX island (degrades to TeX source).
  Vendored like htmx, no CDN.
- **Editor/split/export = Phase 3 cataloging desk** (CodeMirror island
  already in the plan) — not a bolt-on.

## Existing

- Per-reader MCP session pool: idle eviction is lazy/inline; if pool churn
  ever matters, consider background sweep + metrics.
- Broker `rateLimit.tokens` raised to 60/min during 429 incident — drop to
  ~30/min now that reads are 1 request (deploy-side).
- `mark_worlds` enumeration tool on the broker would enable a generated
  floor page (today the root hub serves by convention).
- Frontmatter strip is render-side only; the publishers that wrote metadata
  fences into bodies should be found and fixed at source.


## Related documents

- [ADR 0003 HTMX SSR philosophy](/demarkus-library/adr/0003-htmx-ssr-philosophy.md): rendering split and JS island concessions
- [Phase 3 cataloging desk](/demarkus-library/plans/phase-3-cataloging-desk.md): editor, split, export deferred here
- [Audit 2026-06-18](/demarkus-library/audit-2026-06-18.md): prioritized hardening backlog
- [Handler decomposition plan](/demarkus-library/plans/handler-decomposition.md): the sequence that pays this page down


## Backlinks depend on a document having been rendered

The referenced-by block reads the R3 observed-links map, which is populated when a document pane renders, not by crawling. The map is in-memory and per-pod, so every library restart empties it and a document shows no backlinks until each linking document is opened again. That is what made the edition bug so visible: editions were browsed and recorded, while some real sources had not been opened since the last roll.

Worth deciding whether the margin should fall back to the hub `/graph.md` (which the floor already parses) when the observed map has nothing for a document, so a cold pod shows the durable inbound edges rather than an empty list. Recorded 2026-08-18 alongside the fix in [/demarkus-library/debugging.md](/demarkus-library/debugging.md).


## Functions returning more than two values

The shared guidelines say never return more than two values unless one is
`error`, and both the 2026-09-09 sweep and the handler-decomposition plan
recorded this as already holding. It does not. An AST sweep finds seven
functions returning three values where the third is not an error, and found
nine before the parameter-struct branch fixed two of them in passing.

The one worth a decision is the OAuth flow's `Begin`, which returns
`(authURL, state, verifier string, err error)` — three interchangeable
strings, the same defect the plan cites for `Publish`. It appears in the web
adapter's port, the broker implementation in `cmd/`, and one fake, so a
result struct is a small change, but it is the auth cluster and did not
belong on a branch scoped to the ports and the drawing code.

The other four are the comma-ok idiom: `returnTrail`, `rewriteHref`,
`previewableAnchor` and `paneAddrFromRoute` each return two heterogeneous
values plus a trailing `bool`. Reading those as violations would be
pedantic, but the guideline as written does not carve them out, so either
the guideline should name the exception or the sweep should stop counting
them.

Fixed in passing on the parameter-struct branch because they sat in the
files being refactored and fed the same call chain: `wmRankDocs` now returns
a `wmRanking` plus the linked count, and `floorRing` returns a
`floorRingGeom` instead of three loose ints.


## Resolved

The `ReadingHandler` breadth entry was paid off on 2026-09-10 (PR 73): the shared nav chrome moved to one type built once per request, and each surface family got its own handler over the slice of the port it drives. Steps 1 to 3 of the handler decomposition plan.

The wide-parameter-list entry was paid off the same day on
`refactor/param-structs` (steps 4 and 5). All three clusters converted
together: `domain.PublishRequest` and `domain.LookupRequest` across the
port, the service and the broker, world and federated adapters; `edgeEnd`,
`edgeStyle`, `ellipse`, `wmDraw`, `wmAgg` and `wmRanking` across the graph,
world map and floor builders; and `paneRequest` for the web adapter's
`paneView`. The sweep that found 22 wide signatures now finds none. SVG
output was byte-pinned before and after, and the route registration set
still matches main.