feat(reader): FR4 per-stream completeness flags (Phase 0)

[ashish-jabble]

Phase 0 of #58 — the first independently-shippable slice. FR4 only: completeness flags. No persistence work.

What

Every /logs/{sys,api,audit} read now reports, per stream, whether its rows came from the durable store or a bounded ring:

GET /logs/sys   → { "rows": [...], "completeness": { "sys": "ring" } }
GET /logs/api   → { "rows": [...], "completeness": { "api": "ring" } }
GET /logs/audit → { "rows": [...], "total": …, "completeness": { "audit": "store" } }

With persistence still off (the default), audit is served from the store and api/sys from rings — so the values are static today. The point of this PR is not the value; it is locking the response envelope now so consumers can start reading completeness, and so Phase 1 (FR1) only has to flip a value, not change the contract.

Design notes

• One-key map, not a flat scalar. Single-stream endpoints emit {"sys":"ring"} etc. — the same shape FR2's /logs/correlate will merge, so that endpoint becomes a trivial assembly later.
• One resolver seam. persist_streams (Python, a router() kwarg) / persistedStreams (Go, an Engine field seeded to {audit} in Init) is the single place Phase 1 repopulates from real config. Handlers do not change again.
• Additive only. Existing keys (rows, total, limit, offset, next_after) are untouched; the not-initialised error paths also gain the flag so consumers parse one uniform shape on every response. Satisfies the issue's "behavior unchanged when new config absent" criterion.
• Python + Go parity (FR5).

Deferred (intentionally)

Truncation honesty (ring-at-capacity / limit-hit signaling) is not in this PR — kept to store-vs-ring per the phased plan. A ring genuinely cannot tell you whether matching older rows were evicted, only that loss is possible; that nuance belongs with Phase 1.

Tests

python/tests/test_completeness.py and go/completeness_test.go cover: store-vs-ring defaults, the persist_streams override flipping api/sys to store, additive-key preservation, and error-path flags.

Note on local verification: I could not run either suite on my machine — both packages load the native libfasten_core and only a Linux .so is present (macOS needs a .dylib), with no Rust toolchain to rebuild it; the existing suites fail the same way locally. As far as the environment allowed: go vet . passes (compiles the package including the new test), py_compile passes, and import fasten + router construction run cleanly under a stubbed core.

Refs #58

[ashish-jabble]

BEFORE (main) — no honesty signal

GET /logs/sys   → {"rows":[{"level":"error","event":"db.timeout","request_id":"req-demo-123",...}]}
GET /logs/api   → {"rows":[ {GET /v1/health 200 ...}, {POST /v1/checkout 502 ...} ]}
GET /logs/audit → {"rows":[...],"total":1,"limit":100,"offset":0}

No way to know whether sys/api are the full history or a truncated ring window.

AFTER (feat/phase0-completeness-flags) — every read declares its source

GET /logs/sys   → {"rows":[...same row...],     "completeness":{"sys":"ring"}}
GET /logs/api   → {"rows":[...same 2 rows...],  "completeness":{"api":"ring"}}
GET /logs/audit → {"rows":[...],"total":1,"limit":100,"offset":0,"completeness":{"audit":"store"}}

The diff

Endpoint	BEFORE	AFTER
/logs/sys	(no field)	"completeness":{"sys":"ring"}
/logs/api	(no field)	"completeness":{"api":"ring"}
/logs/audit	(no field)	"completeness":{"audit":"store"}
existing keys (rows, total, limit, offset)	present	unchanged (additive)

[praveen-garg]

1. The name oversells what it measures. completeness does not tell a consumer whether
   this response was truncated. A ring that overflowed and silently dropped 3 000 rows
   reports exactly "ring" — identical to an empty ring that lost nothing. It's a static
   class label, not a per-response gap signal. At Phase 0 that's a fine scaffold, but the
   name invites readers to over-trust it. Worth a doc note (or renaming the value to
   describe the guarantee, e.g. durable/best-effort, rather than the mechanism store/ring).
2. Go/Python divergence in where the default lives. Go hardcodes a nil-map fallback in
   the resolver itself (persistedStreams == nil && stream == "audit" → store), so a
   never-Init'd Go engine can never express "audit is a ring." Python keeps the default in
   the router constructor (frozenset({"audit"})), and
   test_empty_persist_streams_makes_audit_ring proves there's no hardcoded audit
   special-case. Harmless today (Init always seeds the map), but it's a latent asymmetry if
   Phase 1 ever wants audit-as-ring.
3. Minor: Python's audit error path returns completeness+error but omits limit/offset
   that the success path carries, so "uniform shape" isn't literally uniform — consistent
   with the pre-existing error path, not a regression.