HTTP API: add read endpoints needed for dashboard HTTP-mode support

[spranab]

Context

wysie/yantrikdb-hermes-dashboard is a local-first FastAPI dashboard for browsing yantrikdb stores. Today it only supports embedded-mode SQLite deployments — cluster/HTTP deployments (yantrikdb-server) are locked out because the dashboard reads SQLite directly.

We're planning to add an HTTP backend to the dashboard so it works against a yantrikdb-server cluster the same way it works against an embedded SQLite file. The plugin's existing client.py already covers 7 of the dashboard's calls (/v1/health, /v1/stats, POST /v1/recall, GET /v1/conflicts, POST /v1/conflicts/{id}/resolve, POST /v1/think, POST /v1/forget). The rest are missing.

This issue tracks adding the missing read-only endpoints to the yantrikdb-server HTTP API. They wrap engine functions that already exist (the dashboard does the equivalent via raw SQL on a SQLite file) — work is HTTP-layer wiring + JSON serialization, not new engine capabilities.

Endpoints to add

All read-only, all under /v1/:

GET  /v1/memories?namespace=&status=&domain=&source=&limit=&offset=&q=
GET  /v1/memory/{rid}
GET  /v1/identity-scope
GET  /v1/entities?namespace=&limit=
GET  /v1/graph/{entity}?depth=&namespace=
GET  /v1/sessions?namespace=&limit=
GET  /v1/stale?namespace=&before=
GET  /v1/upcoming?namespace=&within=
GET  /v1/patterns?namespace=
GET  /v1/triggers?namespace=
GET  /v1/export/memories.jsonl?namespace=

Phased delivery

Phase	Endpoints	Unlocks
Phase 1	/v1/memories, /v1/memory/{rid}, /v1/identity-scope	Memory browser + Identity & Scope page (the two most-used views)
Phase 2	/v1/entities, /v1/graph/{entity}	Visualizer + entity graph (the screenshot moment)
Phase 3	/v1/sessions, /v1/stale, /v1/upcoming, /v1/patterns, /v1/triggers, /v1/export/memories.jsonl	Lifecycle + analytics + export

Engine effort estimate: ~3 days total split across phases (~1 day per phase).

Mapping to existing engine functions

Each endpoint is a thin HTTP wrapper around code that already runs inside the embedded engine (the dashboard does the equivalent via raw SQL today). No new engine capabilities required.

Example shape (Rust pseudo-handler):

async fn list_memories(
    Query(filters): Query<MemoryFilters>,
    State(engine): State<Engine>,
) -> Result<Json<MemoryListResponse>, ApiError> {
    let memories = engine.list_memories(&filters)?;
    Ok(Json(MemoryListResponse {
        items: memories,
        total: memories.len(),
    }))
}

Response shapes should match what the dashboard's current SQL queries return — see wysie/yantrikdb-hermes-dashboard/app.py for the existing shape (look for endpoints like /api/memories, /api/memory/{rid}, /api/identity-scope, etc.).

Priority

P3 — schedule after:

1. Reembed API delivery (in-flight, end-of-week target)
2. v0.5 deep-research substrate (14-question payload sent separately via swarm)

This doesn't block anything in flight; it unlocks dashboard HTTP-mode for cluster deployments, which is currently a "no, can't use the dashboard" answer for anyone running yantrikdb-server.

Out of scope

• Mutating endpoints (create/update/delete memories) — those already exist via POST /v1/remember, POST /v1/forget, etc., and the dashboard's Admin Mode uses them. This issue is only the read-side gap.
• Owner-scoping derivation logic — already engine-side per v0.4.10/v0.4.11 of the plugin; this issue just needs it exposed via /v1/identity-scope.
• Authentication changes — existing Bearer-token auth applies to all new endpoints; no change needed.

Related

• Plugin (client side that will consume these): yantrikos/yantrikdb-hermes-plugin
• Upstream dashboard (will receive a PR adding HTTPBackend that calls these endpoints): wysie/yantrikdb-hermes-dashboard
• Existing client implementation (reference for auth/retry/error patterns): yantrikdb-hermes-plugin/yantrikdb/client.py

[spranab]

Scope is clean — these are all thin HTTP wrappers over engine surfaces that already exist, and the 3-phase breakdown maps naturally to deliverable PRs. Happy to take this once the reembed + deep-research work clears. A few architectural questions worth nailing down BEFORE Phase 1 implementation so we don't bake mistakes into 11 endpoints' worth of API surface:

Architecture questions

1. Pagination convention

The proposal shows limit=&offset= for /v1/memories and /v1/entities. Offset pagination is fine for static datasets but unstable for a moving one — rows shift as new memories are written underneath, the same offset returns different content across pages. Two alternatives:

Style	Pros	Cons
Offset/limit (proposed)	Familiar; pages can jump arbitrarily	Drift under concurrent writes; not stable for export
Cursor (after=<rid>&limit=)	Stable iteration even with writes	No random-page jumps; harder for dashboard UI
Hybrid (cursor for export, offset for UI)	Right shape per use case	Two conventions to remember

Dashboard UI use case probably wants offset (jump to page N). Export use case wants cursor (stable iteration). Lean toward hybrid — happy to go either way; want to lock the choice before writing the first handler. Your call.

2. Auth + scoping

The plugin shipped owner-scoping in v0.4.10 (PR #13). /v1/memories returning ALL memories across ALL owners is the wrong default — same data-exposure risk that owner-scoping was added to address. Should the read endpoints respect the same scoping convention as the existing write endpoints? Concretely:

• Token-based auth (same as POST /v1/remember)
• Token-derived namespace + owner scope applied to every listing
• ?namespace= and ?owner= query params constrained by the token's authorized scopes (can't override to broader than the token allows)

This is the "safe by default" version. Alternative is wide-open reads + dashboard layer enforces — which I think is wrong because it leaks the burden onto every dashboard implementation, and any future non-dashboard consumer.

3. Cluster mode RYW for /v1/memory/{rid}

/v1/memories listing can serve from any node (eventual consistency fine for browsing). But /v1/memory/{rid} immediately after a POST /v1/remember should return the just-written row — read-your-writes semantics. RFC 010 PR-6.4 added the routing layer for this exact case. We should reuse it (route point-reads through the leader OR via cluster-seq RYW). Not a new design; just a note that we need to wire it for these new endpoints.

4. Streaming for /v1/export/memories.jsonl

Trader-class data is 1.7 GB+. A buffered response builds the whole JSONL in memory before flushing — kills the server on large namespaces. The export endpoint MUST be chunked-transfer-encoded with streaming serialization (yield-per-row from the engine cursor, not collect-then-serialize). Worth flagging explicitly as a non-functional requirement in the spec.

5. Error shape consistency

What's the canonical error envelope for the new endpoints? Looking at existing:

• POST /v1/remember returns {"rid": ...} on success, what on 4xx/5xx?
• POST /v1/recall returns {"results": [...]} on success, ditto.

If there's no existing convention codified, this is a chance to lock one (e.g. {"error": {"code": "...", "message": "...", "hint": "..."}}). Otherwise dashboard error handling becomes per-endpoint guesswork. Worth a quick scan of http_gateway.rs to see what shipped before.

6. /v1/identity-scope shape

This is the most yantrikdb-specific endpoint and the one where dashboard expectations matter most. The plugin v0.4.10+ has owner-scoping logic; this endpoint should expose the same logic the plugin uses, not reimplement it. Concretely: the response should let the dashboard derive (a) what owners exist, (b) what the requester's effective scope is, (c) how to render the "Identity & Scope" page. Worth pulling the plugin's existing structure (look in plugin's owner_scope.py or equivalent) as the source of truth and mirroring it in the engine + HTTP exposure.

Phase-1 implementation plan (when it's time)

When this clears P3 scheduling, I'd want to ship Phase 1 as one PR establishing:

• All conventions above (pagination shape, auth/scoping pattern, error envelope, RYW routing)
• Three endpoints (/v1/memories, /v1/memory/{rid}, /v1/identity-scope)
• Integration tests against the production handler (per test-coverage gap: http_integration.rs uses mock handlers, not production handlers (follow-up to #37) #34 discipline — no mock router)
• OpenAPI schema fragment (or equivalent) so the dashboard can codegen the client cleanly

Estimated 1.5-2 days for that combined PR. Phase 2/3 are then mechanical extensions following the same pattern, ~1 day each.

Coordination with wysie

Worth pinging wysie on the dashboard repo to confirm the endpoint shapes match what their FastAPI implementation expects. They've been the best external feedback channel we've had — pre-implementation review on the spec is cheap; post-implementation discovery of "wait, the dim of the response shape is wrong" is expensive.

Sequence I'd recommend

1. First: answer the 6 architecture questions above (probably 15-30 min of decisions; happy to draft proposals if useful).
2. Second: wysie confirms endpoint shapes against the dashboard's actual usage.
3. Third: Phase 1 PR (~2 days when slot opens).
4. Fourth: Phase 2 + 3 in separate PRs.

Out of scope for this comment: actual implementation. Just engaging with the spec and flagging decisions to lock first. Standing by for your calls on the 6 questions whenever you want to drive it.

[spranab]

Brainstorm synthesis (gpt-5.5 + deepseek-chat + Claude, 3 rounds)

Ran a 3-round design brainstorm on the 6 architecture questions. Strong convergence on 5 of 6 — pagination remains an empirical question rather than an architectural one. Full transcript available; condensed result below.

✅ LOCK NOW (all 3 models converged)

1. Auth/scoping default: strict, token-derived.
   Query params may narrow scope, never broaden. Admin / "show everything" requires an explicit grant. The server is the security boundary; not the dashboard, not future consumers.

2. Error envelope: structured (option b) with stable codes.

   {
     "error": {
       "code": "namespace_not_found",
       "message": "Namespace not found.",
       "hint": "Check the namespace parameter or call /v1/identity-scope.",
       "request_id": "req_..."
     }
   }

   Maintain docs/error-codes.md, generate it from a Rust enum so docs and implementation cannot drift. Do NOT use RFC 7807 (too verbose for our use case). Do NOT mix shapes (simple-for-4xx + structured-for-5xx) — one envelope everywhere.

3. Streaming export: JSONL, chunked, separate memory:export permission, schema sibling.
   Content-Type: application/x-ndjson. Yield-per-row via Body::from_stream. Add GET /v1/export/memories.schema.json for field definitions. Export is qualitatively different from /v1/memories reads — it's bulk exfiltration capability, gate separately.

4. Read-your-writes for /v1/memory/{rid}: ?min_seq=N from write response, leader fallback when omitted, actionable hint on 404.
   Write responses include cluster_seq. Clients that need read-your-writes pass it on subsequent reads. Replica 404s in cluster mode should leader-verify before final 404 OR include hint {"hint": "memory may be replicating; retry with ?min_seq=<seq>"}. Preserves follower read scale for the 99% case (clicking old memories from lists) while keeping the dashboard's "I just wrote this" UX correct.

5. /v1/identity-scope: schema-versioned, explicit effective_scope, items array.

   {
     "schema_version": 1,
     "principal": {"kind": "token", "id": "tok_..."},
     "effective_scope": {
       "admin": false,
       "namespaces": ["default", "research"],
       "owners": ["alice"],
       "permissions": ["memory:read", "memory:recall"]
     },
     "grants": [{"namespace": "default", "owner": "alice", "role": "reader", "permissions": [...]}]
   }

   Dashboard reads effective_scope directly — no client-side derivation.

📋 DECISION 0 — load-bearing action item

Before writing any handler, capture wysie's dashboard JSON fixtures. All three models (and I) elevated this above the six abstract decisions. Operationally:

1. Inspect wysie/yantrikdb-hermes-dashboard/app.py
2. For each dashboard route with an analog in our 11 endpoints, capture the JSON shape it produces today from embedded SQLite
3. Store fixtures in docs/api-fixtures/ or tests/fixtures/
4. Each handler's integration test asserts the response matches the corresponding fixture
5. Document any deliberate divergences (auth wrapping, error envelope, pagination metadata are the expected exceptions)

This subordinates API design to consumer reality. Without this, we ship 11 endpoints that look clean architecturally and require dashboard-side translation middleware.

🤔 DEFER (resolve at Decision 0 / fixture review time)

6. Pagination shape. Cursor-first is the conservative default per all 3 models ("add offset later is cheap; remove offset later is hostile"). But the empirical question is: does wysie's dashboard UX use jump-to-page-N navigation, or infinite-scroll / load-more? If the former, we need offset support; if the latter, cursor-only is correct.

   • Recommended starting position: cursor-only with ?limit=&after=, opaque cursor encoding (created_at_desc, rid_desc). Add offset to /v1/memories specifically if Decision 0 proves dashboard depends on it.

7. Exact response field names. Lift from wysie's fixtures.

8. Patterns/triggers pagination. Unpaginated if bounded diagnostic views; cursor convention if unbounded.

❓ ASK PRANAB (3 genuine unknowns)

1. Cluster-seq wait primitive availability — does RFC 010 PR-6.4's routing layer expose a wait-for-min-seq primitive the HTTP gateway can call, or does the gateway need to implement waiting itself?
2. Unauthorized-namespace policy — for namespaces not visible to the caller: return 403 forbidden (reveals existence) or 404 not-found (indistinguishable)? Lock once, apply uniformly to all 11 endpoints.
3. Pre-existing permission scope naming — is there an established convention in yantrikdb-server token claims for permission names? If yes, match it. If no, lock the naming as part of Phase 1 (proposed: memory:read, memory:export, memory:graph:read, scope:read, admin:read).

Strongest disagreement that emerged

Pagination remains the one empirical question. Both sides have valid arguments — cursor-first defends against silent skip/duplicate under concurrent writes; offset is what SQLite-derived dashboards naturally expect. The synthesizer's recommendation: cursor-only initially, add offset later if Decision 0 proves the dashboard genuinely needs jump-to-page-N navigation. Adding offset later is backward-compatible. Locking a wrong pagination shape across 11 endpoints is permanent.

Phase 1 PR scoping (when slot opens)

One PR establishing all 6 conventions + 3 endpoints (/v1/memories, /v1/memory/{rid}, /v1/identity-scope) + integration tests against the production handler (per #34 discipline) + OpenAPI/JSON-schema fragment + docs/error-codes.md + docs/api-fixtures/ for the contract.

Estimated 1.5-2 days when slot opens, assuming Decision 0 fixtures and the 3 Pranab-questions are resolved beforehand.

---

Brainstorm: 3 rounds, 3 models, 434s, ~30k tokens. Session d6d9b6ca-735f-4b80-9e65-63bb6aea72f1.

[spranab]

Decision 0 complete — fixture analysis of wysie/yantrikdb-hermes-dashboard

Pulled the actual endpoint definitions from wysie/yantrikdb-hermes-dashboard/app.py. This overrides parts of the brainstorm synthesis with empirical data. Three of the five locked decisions survive verbatim; two need updating; the analysis surfaced three new findings worth capturing.

🔄 OVERRIDE: pagination is offset/limit, NOT cursor-only

The dashboard ships offset-based pagination today. Confirmed from GET /api/memories:

?namespace=&status=&domain=&source=&memory_type=&q=&limit=50&offset=0&sort=created_at

Response envelope: {total, limit, offset, items[]}. Max limit enforced at 200. No cursor anywhere.

The brainstorm's conservative "cursor-only initially, add offset later" was good design hygiene in the abstract but the actual consumer is offset-shaped today. Cursor-only would force wysie to rewrite the dashboard's HTTP-mode code path. Translation layer = anti-pattern.

Revised pagination decision:

• Lock offset/limit as the primary pagination convention for list endpoints
• Match the dashboard's exact response shape: {total, limit, offset, items[]}
• Cursor support is optional follow-up only if an export-class consumer needs stable traversal under writes
• Document offset as "UI convenience, drift-vulnerable under concurrent writes" — the warning stays even if the implementation is offset-first

🆕 OVERRIDE: identity-scope is RICHER than we proposed

The dashboard's GET /api/identity-scope returns a deeply nested structure with FOUR top-level collections, not the flat-grants array we agreed on in the brainstorm:

{
  "identity_scope": {
    "identities":     [{ "id": "...", "label": "...", "private_scope": "...", "resolved_scope": "...", "source": "..." }],
    "actors":         [{ "platform": "...", "actor_id": "...", "identity": "...", "legacy_scope": "...", "source": "...", "alias": "..." }],
    "spaces":         [{ "id": "...", "scope": "...", "label": "...", "source": "..." }],
    "conversations":  [{ "platform": "...", "conversation_id": "...", "scope": "...", "label": "...", "source": "..." }]
  },
  "namespace_inventory": [{
    "namespace": "...", "count": 0, "mapped": true, "mapped_scope": "...",
    "mapped_to": "...", "mapping_type": "...", "mapping_source": "...", "derived_by_config": true
  }],
  "summary": { "identities": 0, "actors": 0, "spaces": 0, "conversations": 0, "unmapped_namespaces": 0 },
  "imported_identity_scope": {},
  "runtime_scope": {}
}

This is the plugin v0.4.10 owner-scoping logic shaped as a dashboard response. It distinguishes identities (canonical owners), actors (platform-specific aliases like telegram:wysie), spaces (logical scopes), conversations (per-chat scopes), and a namespace inventory with mapped/unmapped status.

Revised identity-scope decision:

• Match the existing nested shape verbatim — identities, actors, spaces, conversations, namespace_inventory, summary
• Add schema_version: 1 as proposed
• Add effective_scope block (still valuable — saves the dashboard reverse-engineering)
• The endpoint becomes the engine's view of the plugin v0.4.10 owner-scoping logic, exposed verbatim

🔒 CONFIRMED: 3 brainstorm locks survive

Decision	Status	Why fixtures support it
Auth: strict token-derived scoping	✅ Lock	Dashboard runs its own admin/password layer separately; server token auth is orthogonal
Error envelope: option (b) structured	✅ Lock	Dashboard doesn't expose a canonical error shape; we design ours freely
Streaming export: JSONL + separate permission	✅ Lock	No export endpoint in dashboard yet; Phase 3 design unconstrained
RYW: ?min_seq=N + leader fallback	✅ Lock	Dashboard's /api/memory/{rid} is a simple lookup; min_seq applies cleanly

🆕 NEW: scope boundaries clarified

Issue #39 listed 11 endpoints. The dashboard actually has 17 endpoints, but six are out of scope for yantrikdb-server:

Endpoint	Status
POST /api/identity-scope	Dashboard-local config (admin) — out of scope
GET/POST /api/settings	Dashboard settings — out of scope (dashboard-local config)
GET /api/auth/status + POST /login + POST /logout	Dashboard-side password auth — out of scope
POST /api/memory/{rid}/forget	Already exists as POST /v1/forget

Verdict: The 11-endpoint spec stands. Settings + auth endpoints are dashboard-local concerns — they should NOT graft onto yantrikdb-server.

🆕 NEW: field naming locked from fixtures

Memory rows carry 25 columns per the dashboard's SELECT:

• Memory ID is rid (not id)
• Text is text (not content)
• Timestamps come as both numeric Unix float AND ISO string: created_at + created_at_iso
• Embedding info is embedding_bytes (length in bytes) + embedding_model (name)
• Metadata is metadata_json (parsed object, not raw blob)
• Namespace is namespace

Full memory schema observed: rid, type, text, created_at, updated_at, importance, half_life, last_access, access_count, valence, consolidated_into, consolidation_status, storage_tier, metadata, namespace, certainty, domain, source, emotional_state, session_id, due_at, temporal_kind, tombstone_reason, embedding_model, embedding_bytes.

🆕 NEW: memory detail returns conditional related rows

GET /api/memory/{rid} returns the memory plus three related arrays, included conditionally based on engine table existence:

• consolidation_sources[] — if consolidation_members table exists
• entities[] — if memory_entities table exists
• claims[] — if claims table exists (this is the v0.5 deep-research substrate territory)

Server-side GET /v1/memory/{rid} should match this structure with the same conditional-include semantics.

🆕 NEW: recall has FTS5 keyword fallback

The dashboard's POST /api/recall falls back to FTS5 (BM25) or LIKE keyword search if semantic returns empty, and includes a fallback: "fts5_keyword" marker on the response. Engine supports this via RFC 008. Server should expose the same fallback semantics.

Updated synthesis

LOCKED (fixture-verified):

1. Pagination = offset/limit with {total, limit, offset, items[]} envelope. Max limit 200. Cursor optional follow-up.
2. Auth = strict token-derived (server boundary; dashboard auth is orthogonal).
3. Errors = structured option (b) with stable codes registry.
4. Export = streaming JSONL + separate permission (Phase 3, no fixture constraint).
5. RYW = ?min_seq=N with leader fallback + actionable 404 hint.
6. Identity-scope = match dashboard's nested shape (identities/actors/spaces/conversations + namespace_inventory + summary), add schema_version and effective_scope on top.
7. Field naming = rid / text / created_at+created_at_iso / embedding_bytes / metadata_json / namespace — match dashboard contract.
8. Memory detail = conditional consolidation_sources[] / entities[] / claims[] if respective engine tables exist.
9. Recall = expose FTS5 keyword fallback with fallback: "fts5_keyword" marker.

STILL NEEDS PRANAB:

1. Cluster-seq wait primitive availability in RFC 010 PR-6.4 — does the wait-for-min-seq exist in the routing layer, or does the HTTP gateway implement it?
2. Unauthorized-namespace policy — 403 reveals existence, 404 indistinguishable. Pick one.
3. Permission scope naming — are memory:read, memory:export, memory:graph:read, scope:read, admin:read the convention, or is there a pre-existing scheme?

Phase 1 PR — sizing unchanged at ~1.5-2 days

Now backed by fixtures:

• 3 endpoints: /v1/memories (offset shape + 200 cap), /v1/memory/{rid} (with conditional includes), /v1/identity-scope (nested shape from dashboard + schema_version + effective_scope)
• Conventions: error envelope + auth + field naming + RYW + FTS5 fallback for recall
• Integration tests against production handler (per test-coverage gap: http_integration.rs uses mock handlers, not production handlers (follow-up to #37) #34 discipline)
• Fixture-asserted contract tests using golden JSON captured from the dashboard analysis

Process note

The brainstorm's "cursor-only initially, add offset later is cheap" framing was theoretically correct but empirically wrong against the actual consumer. Decision 0 IS the bridge between architectural abstraction and consumer reality. Without this fixture capture we would have shipped cursor-only and either forced wysie to write translation middleware OR rewritten the dashboard's HTTP-mode path. Always capture fixtures BEFORE locking response shapes — this was a near-miss.

The dashboard's app.py at https://github.com/wysie/yantrikdb-hermes-dashboard/blob/main/app.py is the source of truth for Phase 1 response shapes going forward.

[spranab]

All three Pranab-questions resolved — Phase 1 unblocked

1. Unauthorized-namespace policy: 403 (Pranab call). Reveals existence; consistent with the strict token-derived scoping. Applied uniformly to all 11 endpoints.

2. Cluster-seq wait primitive: EXISTS. Code survey confirms engine v0.6.5+ shipped wait_for_visible_seq(namespace, min_seq, timeout) -> Result<()> and visible_seq_for(ns) -> u64. Server-side commit/submitter.rs has wait_for_apply plumbing already. The HTTP gateway can call into this for ?min_seq=N RYW semantics directly — no new engine API needed.

3. Permission scope naming: no existing convention in crates/yantrikdb-server/src/ (grep returned empty). Phase 1 PR locks the naming. Proposed:

   • memory:read — list and detail
   • memory:graph:read — entities + graph
   • memory:export — bulk JSONL export
   • scope:read — /v1/identity-scope
   • admin:read — enumerate beyond authorized scope (for admin tokens)

Implementation kickoff

Per @spranab's call: bundle Phase 1 work into the v0.8.17 release narrative (engine bump #38 already merged at d67cd4a).

Starting Phase 1 implementation now on a separate branch. Will open a follow-up PR with:

• 3 endpoints: /v1/memories, /v1/memory/{rid}, /v1/identity-scope
• Conventions locked: offset/limit pagination, structured errors with stable codes registry, strict token-derived scoping with 403 unauthorized, RYW via ?min_seq=N, field naming matching dashboard fixtures (rid/text/created_at+created_at_iso/embedding_bytes/metadata_json/namespace)
• Integration tests against production handlers (per test-coverage gap: http_integration.rs uses mock handlers, not production handlers (follow-up to #37) #34 discipline)
• Fixture-asserted contract tests using JSON shapes lifted from wysie's dashboard

Estimated 1.5-2 days. Phase 2/3 endpoints follow mechanically.

[spranab]

Surprise from code survey — error envelope scope is bigger than the brainstorm assumed

Starting Phase 1 implementation; ran the code survey first per the discipline. One finding that needs your call before I write the first handler:

What's there today

crates/yantrikdb-server/src/http_gateway.rs ships a Option-(a) error envelope universally:

type AppError = (StatusCode, Json<Value>);

fn app_error(status: StatusCode, message: impl Into<String>) -> AppError {
    (status, Json(json!({ "error": message.into() })))
}

Every existing endpoint returns {"error": "string"}. The brainstorm explicitly chose Option (b) — {"error": {"code", "message", "hint", "request_id"}} — and also explicitly rejected mixing shapes: "Do not mix simple 4xx and structured 5xx. Mixing creates client complexity forever."

So there are three honest paths:

1. Migrate all existing endpoints to Option (b) as part of Phase 1. Real work — touches every app_error(...) call site in http_gateway.rs (~80 instances by grep). Lockstep migration ensures the dashboard sees a consistent error envelope. ~3-4 extra hours.

2. Phase 1 ships only the 3 new endpoints with Option (b); existing endpoints stay Option (a). Violates the brainstorm's "no mixed shapes" lock. Dashboard would need to handle both — defeats the point.

3. Phase 1 uses Option (a) like everything else; migration to Option (b) is a separate PR before v1.0. Defers the discipline but ships Phase 1 faster.

My recommendation: Path 1 (lockstep migration). It's not a huge change — app_error is one helper, the call sites are mechanical to update, and tests pin the codes. Adds ~3-4 hours to Phase 1 (so ~2 days total instead of 1.5-2). The alternative (mixed shapes) is the recurring pattern we keep flagging as anti-pattern.

Want me to proceed with Path 1? Or do you prefer Path 3 to ship Phase 1 faster and defer the migration?

What's also locked from the code survey (no decisions needed)

• Auth module exists at crates/yantrikdb-server/src/auth/provider.rs — authenticate() returns AuthOutcome / AuthError. Token-derived scoping can plug into the existing middleware in server.rs:261.
• /v1/sessions POST already exists for session creation. Issue HTTP API: add read endpoints needed for dashboard HTTP-mode support #39's GET /v1/sessions?namespace=&limit= (Phase 3) needs either method-multiplexing on the same path (axum supports .get(...).post(...)) or a separate path like /v1/sessions/list. Not Phase 1 — flagging early.
• /v1/claims GET already exists. Phase 1's /v1/memory/{rid} conditional-include of claims[] can reuse the same engine fetch.

Where I am

• ✅ PR deps: bump engine yantrikdb 0.7.16 -> 0.7.17 #38 merged (engine bump 0.7.16 → 0.7.17 at d67cd4a)
• ✅ Branch feat/issue-39-phase-1-read-endpoints created off updated main
• ⏸️ Waiting on your call on the error envelope question before writing handlers

If I don't hear back, my default (per discipline) is Path 1 — lockstep migration. But this is the kind of "scope expansion mid-PR" decision I want explicit on, not silent.