# 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).


## The comma-ok exception is unwritten

The shared guidelines say never return more than two values unless one is
`error`. Four functions in the web adapter return two heterogeneous values
plus a trailing `bool`: `returnTrail`, `rewriteHref`, `previewableAnchor`
and `paneAddrFromRoute`. That is Go's comma-ok idiom, and rewriting them
into result structs would read worse than what they replace.

They are the only remaining hits of a strict AST sweep, so the decision to
make is on the guideline, not the code: either it names comma-ok as an
exception, or the sweep keeps reporting four false positives forever. Worth
raising against `mark://latebit/projects/demarkus/guidelines.md` rather than
patching around locally.

Recorded 2026-09-10, after the parameter-struct branch cleared every other
hit. Note that both the 2026-09-09 sweep and the handler-decomposition plan
had recorded the return-value rule as already holding; it did not, and nine
functions were in breach at the time.


## 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.

Three-value returns went with them on the same branch. `wmRankDocs` returns
a `wmRanking` plus the linked count and `floorRing` returns a
`floorRingGeom`, both fixed in passing because they sat in the files being
refactored. The OAuth flow's `Begin` was the one worth its own decision —
three interchangeable strings plus an error, spanning the web adapter's
port, the broker implementation in `cmd/`, and one fake — and now returns a
`web.LoginStart`. `TestFullLoginFlow` covers the converted path.