soul.demarkus.io:6309/demarkus-library/roadmap.md/v10 draft reader meta

demarkus-library — Roadmap & Resume

Pick-up-where-we-left-off doc. Authoritative plan is /plans/universe-library.md; this tracks status and the queued work. Build model: Opus 4.8 default, Fable 5 for load-bearing transport/auth/concurrency design.

Where we are (2026-06-12, PR #10 merged)

main HEAD f5c8c06 — v0.1.0 released: CI + Release workflows green, tag/GitHub release created, multi-arch image at ghcr.io/latebit-io/demarkus-library:0.1.0, chart at oci://ghcr.io/latebit-io/charts/demarkus-library --version 0.1.0 (version==appVersion==image tag, verified). Details in journal 2026-06-12.

  • Phase 0 foundation spike · Phase 1a reading room (stacks, card catalog, editions, link rewriting, htmx fragment-vs-page).
  • Phase 1b — library card: DONE. Broker confidential web clients (demarkus 117e2a6) · oauth client (PKCE S256, Basic auth with §2.3.1 escaping) · server-side sessions + single-flight refresh · ctx threading on ports · broker MCP WorldGateway with per-reader pooled sessions (1 request per read; fixed the live 429s) · login turnstile (/login, /login/start, /auth/callback, /logout; HX-Redirect for htmx) · composition-root swap DEMARKUS_TRANSPORT=quic|broker · native TLS serving for local e2e (mkcert + hosts-file recipe in journal 2026-06-11). E2e verified live.
  • Multi-world floor + federation (fc4277c): (world, path) addressing, /w/<world>/... routes, federated composite gateway — knowledge-system names via broker, host[:port] via direct QUIC (DEMARKUS_FEDERATION, default true, strict parse). Read token never leaves home host (test-pinned). Cross-world mark:// links clickable; root hub = the floor.
  • Frontmatter strip in markdown adapter (render-side mitigation).
  • Deploy manifests + CI/release — DONE, v0.1.0 shipped (PR #10): root .goreleaser.yml (single-module v tags, goreleaser-pro ~> v2, archives.ids) · COPY-only distroless Dockerfile · helm chart deploy/helm/demarkus-library mirroring broker chart conventions (replicaCount 1 + Recreate — in-memory sessions; trim-aware render-time validate; cleartext-vs-existingSecretRef client secret; pod-level automountServiceAccountToken:false; NetworkPolicy with same-namespace ingress + DNS/443/UDP-6309 egress; 24 helm-unittest tests) · .github/workflows/ ci.yml + release.yml (SHA-pinned actions, read-only default token, release-job-only write scopes, non-cancelling concurrency, main-ref guard on publish, chart lint/unittest gating release, tag rollback on failure) · module paths migrated to latebit-io (demarkus 15cc18b; library requires client v0.12.40 + protocol v0.7.13, replaces dropped; library's own module renamed too) · errcheck cleanup · 13 CodeRabbit findings addressed (11 inline + 2 outside-diff).

How to resume

cd ~/latebit/demarkus-library && go test ./... && go build -o /tmp/dl ./cmd/demarkus-library
# quic mode (no auth, soul world):
PORT=8080 DEMARKUS_INSECURE=true DEMARKUS_HOST=soul.demarkus.io \
  DEMARKUS_AUTH=<token from .mcp.json> /tmp/dl
# broker mode: env per config.go (BROKER_URL, CLIENT_ID/SECRET, REDIRECT_URI,
# WORLD=root, TLS_CERT/KEY for local https) — full recipe in journal 2026-06-11.
# chart checks:
helm lint deploy/helm/demarkus-library && helm unittest deploy/helm/demarkus-library
# install in-cluster:
helm install library oci://ghcr.io/latebit-io/charts/demarkus-library --version 0.1.0 \
  --set library.broker.url=... --set library.broker.clientID=... \
  --set library.broker.existingSecretRef.name=... --set library.broker.redirectURI=... \
  --set library.broker.world=root --set ingress.enabled=true --set ingress.host=...

File map (hexagonal — ADR 0002)

  • internal/core/{domain,port,service} — entities, ports (ctx+world on every method), Read/Browse/History/Search
  • internal/adapter/inbound/web — Echo handlers/routes (/w/:world/...), auth turnstile, session pkg, templates, links.go (cross-world rewriting)
  • internal/adapter/outbound/{world,broker,federated,oauth,markdown} — direct QUIC (token→home only), MCP pool, shape-router, broker OAuth, goldmark
  • internal/adapter/bearer — ctx token contract between middleware & gateway
  • cmd/demarkus-library — composition root, AppConfig, brokerAuth shim
  • deploy/helm/demarkus-library — chart · .goreleaser.yml + Dockerfile at root · .github/workflows/{ci,release}.yml

Next sessions — queued work

1. In-cluster install (deploy item 1 wrap-up)

Chart + image are published. Remaining: register the library's webClients entry in the broker chart values (clientID, sha256 of secret, redirect URI), create the operator-managed client-secret Secret, install with broker URL / world / ingress host / cert-manager issuer.

2. Broker rate limit back down (deploy-side, demarkus repo)

rateLimit.tokens was raised to 60/min burst 30 during the 429 incident. Reads are now 1 request each (session pool) — drop to ~30/min burst ~15 in the broker AppSet values.

3. Rendering upgrades (full split in debt.md)

Order: (a) chroma syntax highlighting via goldmark-highlighting — server-side, zero JS, biggest visible win; bluemonday must allow chroma spans/classes. (b) GFM alerts + emoji extensions. (c) Later, islands: mermaid.js + KaTeX, vendored, degradable (ADR 0003 concessions).

4. Phase 2 — restricted collections (per /plans/universe-library.md)

Per-world/per-path authorization surfaced in the reading room. Depends on broker-side authz semantics — re-read the plan + broker authz.go first.

Standing deferred

  • Backlinks / "cited by" (needs graph crawl; viz deferred).
  • mark_worlds enumeration tool on broker → generated floor page.
  • Find + fix publishers that wrote metadata fences into bodies (strip is render-side mitigation only).
  • Shared session store (or sticky sessions) → unlock replicaCount > 1 + RollingUpdate + PDB in the chart.
  • Adopt demarkus's strict .golangci.yml (18 issues to clean first).
  • Phase 3 cataloging desk (writes, CodeMirror island) · Phase 4 AI librarian (SSE) · Phase 5 public face.

History (condensed — details in journals + ADRs)

  • 2026-06-10: Phases 0 + 1a built and merged (PRs #1–2).
  • 2026-06-11: Phase 1b planned (plan, ADR 0004 — broker loopback finding, device flow rejected, confidential web client chosen) and fully shipped (PRs #3–#9); floor + federation; frontmatter strip. Key endpoint facts: token = /device/token, authorize = /oauth/authorize, /mcp always bearer-gated, no refresh rotation. Gotchas in debugging.md.
  • 2026-06-12: Deploy manifests + CI/release shipped as v0.1.0 (PR #10); module paths migrated to latebit-io (demarkus 15cc18b + library) (journal).

Git / process notes

  • Work on feature/* / fix/* branches. Never auto-commit — Fritz commits and opens PRs; CodeRabbit reviews via .coderabbit.yaml.
  • PR scopes: domain, port, service, web, world, markdown, cmd, view, deps, ci, broker, auth, session, oauth, federated, deploy, docker, helm.
trail
  1. soul.demarkus.io:6309 v10