diff --git a/docs/plans/slice-b-adapter-contract.md b/docs/plans/slice-b-adapter-contract.md new file mode 100644 index 0000000..69936ae --- /dev/null +++ b/docs/plans/slice-b-adapter-contract.md @@ -0,0 +1,228 @@ +# Phase 6 Slice B — read-path adapter contract + +**Status**: prep work (this doc). No implementation. +**Branch**: `mai/kahn/phase-6-sliceB-prep`. +**Author**: kahn (coder, prep mode), 2026-05-29. +**Parent plan**: `docs/plans/mbrian-backend-migration.md` (on `main`). +**Scope boundary**: contract + compile-checking skeleton only. The mBrian-backed implementation waits on m/mBrian#73 landing the migration + handing over the uuid map. + +--- + +## §1 — Consumer inventory + +Every read-path call site against `*store.Store` and the projax-shaped `Item` / `ItemLink` types. The interface (§2) is the union of these. + +### §1.1 — `*store.Store` read methods (source: `store/store.go`) + +| method | signature | semantics | +|---|---|---| +| `ListAll` | `(ctx) ([]*Item, error)` | every live item, ordered by `paths NULLS FIRST, slug` | +| `GetByID` | `(ctx, id) (*Item, error)` | single item by uuid | +| `GetByPath` | `(ctx, path) (*Item, error)` | resolve `dev.paliad` style path to leaf item | +| `GetByPathOrSlug` | `(ctx, key) (*Item, error)` | path first, fall back to bare slug | +| `Roots` | `(ctx) ([]*Item, error)` | items with `cardinality(parent_ids) = 0` | +| `MaiOrphans` | `(ctx) ([]*Item, error)` | mai-managed root items needing classify | +| `ListByFilters` | `(ctx, SearchFilters) ([]*Item, error)` | structured search (status / mgmt / has-link / paths-prefix) | +| `Search` | `(ctx, q, limit) ([]*Item, error)` | trigram + FTS title/content/aliases | +| `AllTags` | `(ctx) ([]string, error)` | union of every item's tags | +| `LinksByType` | `(ctx, itemID, refType) ([]*ItemLink, error)` | one item's links of a given `ref_type` (empty = all) | +| `LinksByRefType` | `(ctx, refType) ([]*ItemLink, error)` | every link of a given ref_type across items | +| `DatedLinks` | `(ctx, itemID) ([]*ItemLink, error)` | one item's links anchored to a date (PER artifacts) | +| `DatedLinksRange` | `(ctx, from, to) ([]*ItemLinkWithItem, error)` | dated links within window, joined with their item | +| `RecentDocuments` | `(ctx, since, limit) ([]*ItemLinkWithItem, error)` | recent dated docs, joined with their item | +| `ItemsCreatedInRange` | `(ctx, from, to) ([]*Item, error)` | items created within window | + +### §1.2 — Consumer call sites (by file) + +Each row = one read-path call site. Direct Pool access (admin.go counts, bulk.go filter-tx, links.go event-date update) is flagged separately at the bottom — those rework targets are out of slice B's read-path scope. + +| consumer | method | use case | +|---|---|---| +| `web/server.go handleTree` | `ListAll`, `AllTags`, `linkKindsByItem` (LinksByRefType ×N) | render /views/tree with chip-counted forest | +| `web/server.go handleDetail` | `GetByPath` ×2 (PER fallback), `LinksByType` (caldav), `DatedLinks` | render /i/{path} detail page | +| `web/server.go parentOptions` | `ListAll` | populate parent