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.

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.