refactor(core): split ReadingService into Reader/Graph/Map/Editor

Author: ontehfritz

internal/adapter/inbound/web/reading_handlers.go

@@ -115,12 +115,8 @@ func (h *ReadingHandler) Root(c *echo.Context) error {
 func (h *ReadingHandler) Doc(c *echo.Context) error {
 	world := c.Param("world")
 	p := "/" + c.Param("*")
-	if strings.HasSuffix(p, "/") {
-		doc, err := h.reading.Browse(c.Request().Context(), world, p)
-		return h.present(c, doc, err, viewOpts{world: world, path: p})
-	}
-	doc, err := h.reading.Read(c.Request().Context(), world, p)
-	return h.present(c, doc, err, viewOpts{world: world, path: p, doc: true})
+	doc, err := h.reading.Open(c.Request().Context(), world, p)
+	return h.present(c, doc, err, viewOpts{world: world, path: p, doc: !domain.IsListingPath(p)})
 }
 
 // Search renders the card catalog (LOOKUP) for the q query in the route's

internal/adapter/inbound/web/reading_handlers_test.go

@@ -93,6 +93,23 @@ func (f *fakeReading) TagCached(_ context.Context, _, tag string) (domain.Docume
 	return f.record("TagCached", tag)
 }
 
+// Open/OpenCached mirror the service: dispatch to Read/Browse by path shape, so
+// tests that assert the recorded Read/Browse calls still hold after the handler
+// addresses resources through Open.
+func (f *fakeReading) Open(ctx context.Context, world, path string) (domain.Document, error) {
+	if domain.IsListingPath(path) {
+		return f.Browse(ctx, world, path)
+	}
+	return f.Read(ctx, world, path)
+}
+
+func (f *fakeReading) OpenCached(ctx context.Context, world, path string) (domain.Document, error) {
+	if domain.IsListingPath(path) {
+		return f.BrowseCached(ctx, world, path)
+	}
+	return f.ReadCached(ctx, world, path)
+}
+
 // RecordLinks is a write, not a read: it stays out of calls/called so the
 // focused-live read-budget assertions keep measuring only world reads.
 func (f *fakeReading) RecordLinks(_, path string, targets []domain.Ref) {

internal/adapter/inbound/web/trail_handlers.go

@@ -194,14 +194,10 @@ func (h *ReadingHandler) readPane(ctx context.Context, addr paneAddr, live bool)
 		return h.reading.Tag(ctx, addr.World, addr.Value)
 	case addr.Kind == paneTag:
 		return h.reading.TagCached(ctx, addr.World, addr.Value)
-	case strings.HasSuffix(addr.Value, "/") && live:
-		return h.reading.Browse(ctx, addr.World, addr.Value)
-	case strings.HasSuffix(addr.Value, "/"):
-		return h.reading.BrowseCached(ctx, addr.World, addr.Value)
 	case live:
-		return h.reading.Read(ctx, addr.World, addr.Value)
+		return h.reading.Open(ctx, addr.World, addr.Value)
 	default:
-		return h.reading.ReadCached(ctx, addr.World, addr.Value)
+		return h.reading.OpenCached(ctx, addr.World, addr.Value)
 	}
 }
 
@@ -247,7 +243,7 @@ func (h *ReadingHandler) paneView(t trail, i int, addr paneAddr, doc domain.Docu
 	}
 
 	content, edges := rewriteLinks(doc.HTML, addr.World, doc.Path)
-	if !reader && addr.Kind == paneDoc && !strings.HasSuffix(addr.Value, "/") {
+	if !reader && addr.Kind == paneDoc && !domain.IsListingPath(addr.Value) {
 		// Feed the observed-links map (R3) from real document panes only —
 		// listings and tag pages are not edge sources. This runs for the
 		// focused pane and its body-only parent, so a doc's edges are recorded
@@ -265,7 +261,7 @@ func (h *ReadingHandler) paneView(t trail, i int, addr paneAddr, doc domain.Docu
 
 	// The overlay (reader) shows the addressed pane's full margin even when it
 	// is not the focused pane — reading mode is not a dead-end.
-	if (focused || reader) && addr.Kind == paneDoc && !strings.HasSuffix(addr.Value, "/") {
+	if (focused || reader) && addr.Kind == paneDoc && !domain.IsListingPath(addr.Value) {
 		vm.HasMargin = true
 		vm.Tags = tagLinks(addr.World, doc.Tags)
 		vm.Properties = doc.Properties

internal/core/domain/addressing.go

@@ -0,0 +1,13 @@
+package domain
+
+import "strings"
+
+// IsListingPath reports whether a (world, path) addresses a directory listing
+// (the stacks) rather than a document. The convention: a path ending in "/" is a
+// listing, anything else is a document. This is the single definition of that
+// addressing rule — the read dispatch (service.Open/OpenCached) and the web
+// adapter's margin/edge-source presentation both consult it, so the two never
+// drift.
+func IsListingPath(path string) bool {
+	return strings.HasSuffix(path, "/")
+}

internal/core/port/port.go

@@ -9,21 +9,31 @@ import (
 	"github.com/latebit-io/demarkus-library/internal/core/domain"
 )
 
-// ReadingService is the inbound (driving) port — the use cases the reading room
-// exposes to its primary adapters (the web adapter). Driving adapters depend on
-// this interface, not on the concrete service.
+// The inbound (driving) port is split into four concerns — Reader, GraphService,
+// MapService, Editor — and composed as ReadingService, the full surface the web
+// adapter drives. The concrete *service.ReadingService satisfies all four; a
+// narrower consumer (a preview-only handler, the Phase 4 librarian needing only
+// reads) can depend on just the slice it uses rather than the whole 20-method
+// surface.
 //
-// Every method takes the request context (cancellation + the logged-in
-// reader's bearer in broker mode, Phase 1b/ADR 0004) and a world: the library
-// spans a universe of worlds, and a document's address is (world, path). A
-// world is either a knowledge-system world name (resolved by the broker) or a
+// Every context-taking method takes the request context (cancellation + the
+// logged-in reader's bearer in broker mode, Phase 1b/ADR 0004) and a world: the
+// library spans a universe of worlds, and a document's address is (world, path).
+// A world is either a knowledge-system world name (resolved by the broker) or a
 // demarkus host[:port] reached directly — the distributed knowledge graph is
 // traversable across both.
-type ReadingService interface {
+
+// Reader is the read side: fetch and render documents, listings, editions, and
+// the catalog, plus the trail engine's cached variants.
+type Reader interface {
 	// Read fetches and renders the document at (world, path).
 	Read(ctx context.Context, world, path string) (domain.Document, error)
 	// Browse renders a directory listing (the stacks) at (world, path).
 	Browse(ctx context.Context, world, path string) (domain.Document, error)
+	// Open reads (world, path), dispatching to Browse for a listing path and
+	// Read for a document (domain.IsListingPath) — so callers address a
+	// resource without re-deciding the listing-vs-document rule themselves.
+	Open(ctx context.Context, world, path string) (domain.Document, error)
 	// History renders the edition history of the document at (world, path).
 	History(ctx context.Context, world, path string) (domain.Document, error)
 	// Search renders the card catalog (LOOKUP) results for query under scope
@@ -36,22 +46,28 @@ type ReadingService interface {
 	// the projection's escape to protocol (ADR 0005 decision 12).
 	Raw(ctx context.Context, world, path string) (domain.RawDocument, error)
 
-	// ReadCached, BrowseCached, and TagCached are the trail engine's
-	// unfocused-pane reads (ADR 0005 decision 9): served from the
+	// ReadCached, BrowseCached, OpenCached, and TagCached are the trail
+	// engine's unfocused-pane reads (ADR 0005 decision 9): served from the
 	// rendered-document cache, reading through on a miss. The focused pane
 	// uses the live methods, which refresh the cache — so a trail click
 	// costs exactly one world read. Without a cache wired they behave as
-	// their live counterparts.
+	// their live counterparts. OpenCached dispatches by path shape like Open.
 	ReadCached(ctx context.Context, world, path string) (domain.Document, error)
 	BrowseCached(ctx context.Context, world, path string) (domain.Document, error)
+	OpenCached(ctx context.Context, world, path string) (domain.Document, error)
 	TagCached(ctx context.Context, world, tag string) (domain.Document, error)
+}
 
+// GraphService is the render-time observed-links graph (R3; ADR 0005 §16): the
+// web adapter records resolved links, the core owns the edge store and answers
+// backlink / neighborhood queries.
+type GraphService interface {
 	// RecordLinks records the in-universe document links observed in the
-	// rendered document at (world, path), replacing any prior observation
-	// (R3; ADR 0005 §16). The web adapter calls this after resolving links
-	// (rewriteLinks owns the URL scheme); the core owns the edge store. This
-	// is the render-time observed-links map that feeds Backlinks and
-	// Neighborhood — transport-symmetric, no broker graph store required.
+	// rendered document at (world, path), replacing any prior observation. The
+	// web adapter calls this after resolving links (rewriteLinks owns the URL
+	// scheme); the core owns the edge store. This is the render-time
+	// observed-links map that feeds Backlinks and Neighborhood —
+	// transport-symmetric, no broker graph store required.
 	RecordLinks(world, path string, targets []domain.Ref)
 	// Backlinks returns the documents observed linking to (world, path) — the
 	// margin's "referenced by" block and the graph pane's inbound edges.
@@ -62,25 +78,30 @@ type ReadingService interface {
 	// document plus its observed outbound and inbound edges. Store-only (zero
 	// world reads), so it works cold in both transports.
 	Neighborhood(world, path string) domain.Neighborhood
+}
 
-	// Floor assembles the universe view's data (ADR 0005 decision 4):
-	// the authorized worlds and each world's top-importance catalog
-	// entries. Live rebuild; FloorCached serves the last build when the
-	// floor pane is unfocused (the same focused-live policy as documents).
+// MapService assembles the spatial views (ADR 0005 decision 4): the universe
+// floor and one-world map, each with a live build and a cached variant for
+// unfocused panes (the focused-live policy every pane follows).
+type MapService interface {
+	// Floor assembles the universe view's data: the authorized worlds and each
+	// world's top-importance catalog entries. Live rebuild; FloorCached serves
+	// the last build when the floor pane is unfocused.
 	Floor(ctx context.Context) (domain.Floor, error)
 	FloorCached(ctx context.Context) (domain.Floor, error)
-
-	// WorldMap assembles the world-view zoom (ADR 0005 decision 4 — the floor
-	// one zoom in): one world's catalog grouped into directory clusters with
-	// the intra-world edges among the rendered documents. Live rebuild;
-	// WorldMapCached serves the last build for an unfocused/parent pane (the
-	// focused-live policy every pane follows).
+	// WorldMap assembles the world-view zoom (the floor one zoom in): one
+	// world's catalog grouped into directory clusters with the intra-world
+	// edges among the rendered documents. Live rebuild; WorldMapCached serves
+	// the last build for an unfocused/parent pane.
 	WorldMap(ctx context.Context, world string) (domain.WorldMap, error)
 	WorldMapCached(ctx context.Context, world string) (domain.WorldMap, error)
+}
 
-	// EditDraft fetches the source view for the cataloging desk's edit form
-	// (Phase 3): the document's raw markdown plus its current metadata and
-	// version, so the editor pre-fills exactly what the catalog holds.
+// Editor is the cataloging desk's write side (Phase 3).
+type Editor interface {
+	// EditDraft fetches the source view for the edit form: the document's raw
+	// markdown plus its current metadata and version, so the editor pre-fills
+	// exactly what the catalog holds.
 	EditDraft(ctx context.Context, world, path string) (domain.EditDraft, error)
 	// Preview renders edit-buffer markdown to sanitized HTML for the desk's
 	// live preview — the same renderer the reader uses, so what you see is what
@@ -99,6 +120,16 @@ type ReadingService interface {
 	Append(ctx context.Context, world, path, body string) (domain.Document, error)
 }
 
+// ReadingService is the full inbound surface the web adapter drives — the four
+// concerns composed. Driving adapters depend on this (or a narrower slice), not
+// on the concrete service.
+type ReadingService interface {
+	Reader
+	GraphService
+	MapService
+	Editor
+}
+
 // WorldGateway is an outbound (driven) port — read from demarkus worlds. The
 // adapter translates transport status into domain errors and returns markdown
 // bodies for the core to render. Implementations: direct QUIC (world is a

internal/core/service/hardening_test.go

@@ -8,6 +8,35 @@ import (
 	"github.com/latebit-io/demarkus-library/internal/core/domain"
 )
 
+// TestOpenDispatchesByPathShape: Open routes a document path to Read (Fetch) and
+// a listing path to Browse (List); OpenCached dispatches the same way. The
+// gateway verb the service hit is the witness (Read→Fetch, Browse→List).
+func TestOpenDispatchesByPathShape(t *testing.T) {
+	var called string
+	svc := NewReadingService(
+		fakeGateway{called: &called, raw: domain.RawDocument{Body: "x"}},
+		fakeRenderer{html: "x"}, nil,
+	)
+	cases := []struct {
+		name, path, wantVerb string
+		open                 func(string) (domain.Document, error)
+	}{
+		{"Open doc", "/doc.md", "Fetch", func(p string) (domain.Document, error) { return svc.Open(t.Context(), "w", p) }},
+		{"Open listing", "/dir/", "List", func(p string) (domain.Document, error) { return svc.Open(t.Context(), "w", p) }},
+		{"OpenCached doc", "/doc.md", "Fetch", func(p string) (domain.Document, error) { return svc.OpenCached(t.Context(), "w", p) }},
+		{"OpenCached listing", "/dir/", "List", func(p string) (domain.Document, error) { return svc.OpenCached(t.Context(), "w", p) }},
+	}
+	for _, tc := range cases {
+		called = ""
+		if _, err := tc.open(tc.path); err != nil {
+			t.Fatalf("%s: %v", tc.name, err)
+		}
+		if called != tc.wantVerb {
+			t.Errorf("%s hit gateway %q, want %q", tc.name, called, tc.wantVerb)
+		}
+	}
+}
+
 // TestWorldMapCacheTTLAndInvalidate covers the cache primitive directly: a put
 // is fresh within the TTL, stale at/after it, and invalidate drops it outright.
 func TestWorldMapCacheTTLAndInvalidate(t *testing.T) {

internal/core/service/reading.go

@@ -71,6 +71,26 @@ func (s *ReadingService) Read(ctx context.Context, world, path string) (domain.D
 	return doc, nil
 }
 
+// Open reads (world, path), dispatching to Browse for a listing path and Read
+// for a document. The single read-side owner of the listing-vs-document
+// addressing rule (domain.IsListingPath) — callers address a resource without
+// re-deciding it. OpenCached is its cached counterpart for unfocused panes.
+func (s *ReadingService) Open(ctx context.Context, world, path string) (domain.Document, error) {
+	if domain.IsListingPath(path) {
+		return s.Browse(ctx, world, path)
+	}
+	return s.Read(ctx, world, path)
+}
+
+// OpenCached is Open served from the rendered-document cache (trail engine's
+// unfocused panes), dispatching Browse/Read by path shape like Open.
+func (s *ReadingService) OpenCached(ctx context.Context, world, path string) (domain.Document, error) {
+	if domain.IsListingPath(path) {
+		return s.BrowseCached(ctx, world, path)
+	}
+	return s.ReadCached(ctx, world, path)
+}
+
 // ReadCached serves (world, path) from the rendered-document cache, reading
 // through on a miss. Trail engine: unfocused panes only — the focused pane
 // goes through Read, which refreshes the entry (focused-live policy).