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


## 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. Three 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. `brandingWriter` in the web adapter mirrors the `Publish` shape and can only narrow when the port does.

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

The third is inside the web adapter's own pane builders: `paneView` takes six arguments beyond a context, `wmAggNode` eight, `streamAsk` and `worldMapPane` four. Convert these together or not at all — a review bot flags whichever one appears in the diff at hand, and taking that bait leaves the package half-converted.


## 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; steps 4 and 5 are the parameter-struct work described above.