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: rendering split and JS island concessions
• Phase 3 cataloging desk: editor, split, export deferred here
• Audit 2026-06-18: prioritized hardening backlog
• Handler decomposition plan: 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.

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.