# 2026-06-13 — floor live + trail root-listing fix

## Floor in production

R1+R2+floor rolled to the cluster (server 0.17.18, broker 0.1.36, library
0.1.5). The worlds bump needed a one-time orphan-delete recreate (root +
world-a) — caused by the chart stamping churning version labels on the
immutable volumeClaimTemplates; fixed at the chart layer (#184: VCT uses
selectorLabels), so future server bumps are clean. Full rollout detail in
journal 2026-06-12.

## Trail root-listing bug (library PR #16 → v0.1.6)

Fritz hit `{"message":"malformed trail"}` on `/t/u/~/world-a/d/` — the
floor's world-node link (opens a world's stacks = root listing, path "/").
Root cause: the trail parser rejected any pane chunk with an empty value
(`if !ok || value == ""`), but the world-root listing legitimately encodes
as `<world>/d/` (doc-kind, empty value → "/"). Predated the floor — every
root-listing link was broken since R2; the round-trip test only covered a
non-empty subdir (/plans/) and missed root.

Three CodeRabbit findings, all real, fixed in sequence:
1. Root-listing rejected — drop blanket `value==""`, handle per kind (doc
   empty → "/", tag still non-empty).
2. **Two parsers diverged** — `parsePaneChunk` (/t/ chunks) and
   `paneAddrFromRoute` (/w/ route hrefs in the trailize pass) both had the
   bug; fixed one, not the other. Extracted the shared semantics into
   `paneAddrFromParts(world, kind, value)` — single source of truth; the
   two wrappers keep only their input-specific framing (chunk-split+floor
   vs URL-parse+fragment). Divergence now structurally impossible.
3. Tag slash check ran on the RAW value, so `tags/foo%2Fbar` slipped
   through then unescaped to `foo/bar`. Moved empty/slash checks AFTER
   PathUnescape (in the shared helper → fixed for both decoders at once).

Pattern worth keeping: two parsers for the same logical address = a
divergence bug waiting to happen. Share the semantics, not the syntax
framing. Deploy bump library 0.1.5 → 0.1.6 staged (deploy
`fix/library-0.1.6`; clean Deployment roll, no recreate).


## R3 built — previews + backlinks + graph pane (branch feature/reading-room-r3)

The last planned Reading Room phase, built and verified live (QUIC against
soul.demarkus.io). Not committed — awaiting Fritz + CodeRabbit per PR.

**Load-bearing decision (recorded in plans/reading-room.md §"R3 build
decisions"): edge source = render-time observed-links map.** rewriteLinks
already resolves every link to a (world,path); capturing those edges is free
and transport-symmetric (library-internal, no broker store → decision 16
holds). Rejected: broker graph store (broker-only), library-side crawl
(over-built). Honest limit: only edges among docs rendered this pod's lifetime;
hub-sourced topology (addendum 2) is the durable upgrade layered in front
later. Backlinks/graph fill in as the room is read.

**Architecture:** `domain.Ref{World,Path}` + `domain.Neighborhood`. Edge store
is an internal `service.linkGraph` (forward+reverse maps under a mutex),
mirroring floorCache — no new port/adapter/wiring (NewReadingService signature
unchanged). Inbound port gains `RecordLinks` / `Backlinks` / `Neighborhood`.
`rewriteLinks` now returns `(html, []Ref)`; `rewriteHref` returns
`(route, Ref, isDoc)`. Web records edges after rendering doc panes (resolution
stays in web, store in core).

**Pieces:**
- Hover previews: `previewize` wraps in-app doc anchors with
  `preview-host`/`preview-card` + htmx (`mouseenter delay:300ms once` →
  `/w/:world/preview/*` fragment). Pure htmx+CSS, no JS (ADR 0003). One
  component serves body links AND backlink entries. Snippet = first paragraph,
  served from ReadCached (budget-safe). mouseenter overrides click trigger so
  hx-boost nav still works.
- Backlinks margin block ("referenced by") in shared doc-meta — trail URLs on
  the canvas, /w/ permalinks on the single-doc view. Empty ⇒ absent.
- Graph pane: new kind `<world>/g/<path>` via paneAddrFromParts (shared, not
  duplicated). Route `/w/:world/g/*`. SSR SVG (graph.go) — center + backlinks
  (left, blue) + outbound (right, green), each node a plain <a> continuing the
  trail. Canvas island stays unspent. Margin "graph" affordance opens it.

**Docs (decision 14):** docs/trail-format.md + in-universe
mark://soul.demarkus.io/.well-known/library/trails.md (v3) both updated with
the `g` kind — kept in sync.

**Verified live (QUIC):** index.md → 43 wrapped body links; preview fragment
renders title/status/snippet/mark; reading index.md recorded index→architecture
so architecture.md shows index.md under "referenced by" (trail-linked); graph
pane SVG renders, nodes continue the trail; /w/g permalink uses /w/ routes.
`go vet` + full suite green; gofmt clean.

**Open / observed:** broker-mode acceptance is architecturally guaranteed (edge
source is library-internal, no broker-only path) but not run here (needs
interactive OAuth via dev.env) — Fritz to smoke. Visual: a hub doc with ~40
outbound links crowds the graph's right arc (aggregation/cap is future polish,
same family as the floor's satellite crowding note). Suggested PR slices:
(A) edge source + backlinks, (B) previews, (C) graph pane + docs.