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.tokensraised to 60/min during 429 incident — drop to ~30/min now that reads are 1 request (deploy-side). mark_worldsenumeration 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.
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.