soul.demarkus.io:6309/demarkus-library/debt.md/v11 draft reader meta

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.

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.

The broker's Publish comment describes behavior it no longer has

Gateway.Publish in internal/adapter/outbound/broker/broker.go carries a doc comment saying on_conflict is "fail", that an expected-version mismatch surfaces as a reload prompt, that the structural-merge flow is "a later slice", and that the method returns the new version.

None of that is true now. The code picks "merge" for any edit and only uses "fail" on a create (version 0), the merge flow shipped as PublishResult.Merge plus MergeCandidate, and the method returns a PublishResult. The inline comment a few lines lower already explains the real choice by intent, so the header is the only wrong part.

Caught reviewing PR 74, which rewrote that function's signature. The fix was written and then dropped from the branch to keep the merge signature-only, so it is still on main. Small and self-contained: replace the last two sentences of the header and let the inline comment carry the rule.

Every error response is JSON, against the no-JSON rule

ADR 0003 says the room serves HTML and no JSON. Ten handlers return echo.NewHTTPError, and nothing assigns HTTPErrorHandler, so Echo's default writes a JSON body for every 400, 401, 404, 410, 500, 502 and 503 the room produces. The one place this is already acknowledged is page.html, whose hx-status rule suppresses 4xx and 5xx swaps precisely because "Echo's default error body is JSON".

The fix is one custom HTTPErrorHandler rendering an HTML error page, plus letting htmx swap error bodies again once it does. Both halves belong together; doing the handler alone leaves the suppression rule lying about why it exists.

Raised by CodeRabbit against the 410 archived response on PR 76 and declined there, because that response follows the same shape as the 404 beside it and fixing one status while nine others stay JSON would be worse than the current consistent state. Recorded 2026-09-11.

Correction: the read path now answers in HTML

The entry above recorded the JSON error bodies as accepted debt after declining the finding on PR 76. CodeRabbit re-raised it as an outside-diff comment, narrowed to the trail boundary, and the narrow framing was the useful part: the dead ends a reader actually reaches by clicking a link all pass through one function.

presentError now renders an error template with the right status instead of returning echo.NewHTTPError, so every read failure on the trail, document, tag, palette, spatial and edit surfaces answers in HTML. The page carries no nav or palette on purpose; a dead end needs the reason and a way back, not chrome.

What remains JSON is the routes outside the read path: a malformed trail, a missing theme asset, an off-duty librarian, an invalid edit version. Those are machine boundaries rather than reader-facing ones, so the remaining work is smaller and less urgent than this entry first implied.

The original decline reasoning was wrong in one respect worth keeping: it argued that fixing one status while others stayed JSON would be incoherent. True, and the answer was to fix the whole read path rather than the single 410, which is what shipped. Scoping to one shared presenter made a change that looked repo-wide into a local one.

trail
  1. soul.demarkus.io:6309 v11