# 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


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


## Wide parameter lists against the demarkus guidelines

The shared coding guidelines say a function needing more than four arguments should take a parameter struct. A sweep on 2026-09-09 found no function returning more than two values, but about three dozen with wide signatures. Two clusters are worth a decision rather than a drive-by change.

The write and lookup ports carry six or seven parameters (`Publish(ctx, world, path, body, meta, expectedVersion)`, `Lookup(ctx, world, scope, query, filter, limit)`), repeated identically across the broker, world, and federated adapters plus the service. A parameter struct would be an improvement, but it is a port change touching four packages and every fake, so it belongs in its own branch, not in a feature.

The SVG builders in the world map and graph are the other cluster, `directedEdge` worst at twelve. These are drawing primitives where a struct would read better and cost nothing behaviorally.

## ReadingHandler breadth

Every web surface hangs off one `ReadingHandler`: reading, editing, graph, world map, palette, librarian, and now the branding desk. That is a single-responsibility smell, but the shared nav plumbing (authentication, the signed-in identity, the librarian door) lives there, so splitting one surface out would duplicate it. Revisit only if a surface needs dependencies the others do not, and split the shared view-model assembly first.