From f4e24f321d871221c1340cdaede626396de4634f Mon Sep 17 00:00:00 2001 From: "glm-5.3-flash" Date: Sun, 4 Oct 2026 08:47:19 +0000 Subject: [PATCH] docs: streams upgraded to in-scope (operator-authority record) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The inventory graded streams absent because no paused consumer document names it; the operator correction: type-filtered event watching from several places (e.g. repo-change subscriptions in a git app at gitea/gitlab scale) is a basic reactivity requirement — and notify (fire-and-forget, no replay) cannot serve subscriptions honestly. The wanters are applications above the paused crates, which is why the docs don't carry the row. Inventory: streams row recorded on operator authority (the REQ-2 recording convention from alkblobs requirements.md), confidence system gains the operator-authority grade; rate-limits becomes the sole first-cut candidate. phase-0: OQ-ST-01 summary and OQ-ST-04's contract-candidates updated to match. --- docs/research/consumer-inventory.md | 53 ++++++++++++++++++++--------- docs/research/phase-0.md | 21 ++++++++---- 2 files changed, 50 insertions(+), 24 deletions(-) diff --git a/docs/research/consumer-inventory.md b/docs/research/consumer-inventory.md index 101112b..bbfc7c6 100644 --- a/docs/research/consumer-inventory.md +++ b/docs/research/consumer-inventory.md @@ -1,9 +1,10 @@ --- status: draft -last_updated: 2026-10-04 (initial draft — synthesized from the paused -consumers' written artifacts, not from any running consumer. Evidence -quality varies per row and is marked. Rows with weaker evidence are -marked as candidates-for-cut rather than silently included.) +last_updated: 2026-10-04 (streams corrected to documented/in-scope — +operator-authority record: type-filtered event watching from multiple +places, e.g. repo-change subscriptions in a git app. No consumer doc +carries the row yet; applications above the paused crates are the +wanters. rate-limits + result-storage remain the keep-with-flag rows.) --- # alkstore — consumer-driven scope inventory @@ -31,6 +32,11 @@ need for it, quote the need, and grade the evidence. Confidence grades: design has leaned on it yet. - **recalled** — named in research/summary prose as intended, no architecture written against it yet. +- **operator-authority** — the operator records a need the paused + documents don't carry yet (the REQ-2 recording convention from + alkblobs requirements.md), dated; expected where the wanter is an + *application above* the paused crates. Upgrades equivalent to + **documented**. - **absent** — no consumer document names a need. Included by default per the working posture, flagged for cut-at-implementation instead of silently carried. @@ -129,17 +135,25 @@ feature. | Consumer | Evidence | Need | Confidence | |---|---|---|---| -| (none pinned) | — | — | **absent** | +| family-wide (reactivity requirement) | user/planning record, 2026-10-04 (operator's authority — the REQ-2 recording convention) | watching for specific event *types* from several different places at once. Concrete example: a git app at gitea/gitlab scale — users and other apps subscribe to changes on a repo. Many cases along these lines. | **documented** (operator-authority record; no consumer doc has grown the section yet) | -Verdict: **in scope per the working posture, flagged for -cut-at-implementation.** No consumer document names streams. The known -near-need is the *shape* (durable, replayable event log with explicit -offsets) rather than the feature: if alkfs's sync posture (OQ-FS-14) -grows a real multi-node story, or alkblobs' fleet gossip needs a -durable change-log rather than fire-and-forget notify, streams become -load-bearing — and `pg_notify`-plus-table (the pgboss-family pattern) -gives it on the Postgres side almost for free once queues exist. Keep -it, honest about cost, revisit before implementation. +Verdict: **in scope, first-class.** Corrected 2026-10-04 — the initial +draft (earlier the same day) graded this **absent** because no consumer +document names it; that was a fact about the paused documents, not +about the need, and the operator's correction supersedes it. The +reactivity reasoning: notify is fire-and-forget — no replay, no +durability (honker's own split: "streams are the durable cousin") — so +*subscriptions* cannot be built on it honestly. A repo-change +subscription must survive the subscriber being offline at event time +(durable log + per-consumer offset + replay-on-attach is exactly +honker's stream model). Why the paused docs missed it: the consumers +that want it (a git app's subscription surface, cross-app event +watching) are *applications above* the current paused crates, so +nothing written down yet carries the row — which is expected, not +suspicious. Design note for OQ-ST-04: on the Postgres side this is a +NOTIFY-triggered durable event table with per-consumer cursors (the +pg-boss-family shape); the per-consumer offset contract, not the +storage shape, is the seam to pin. ### rate limits @@ -151,7 +165,8 @@ Verdict: **weak candidate — first cut candidate.** No document needs *store-level* rate limiting; alkgit's budgets are enforced above the storage seam with its own mechanism. Keep listed because honker's default set includes it and the machinery is trivial next to queues, -but it is the least-needful row after streams. +but it is now the least-needful row (streams outranked it as of the +2026-10-04 correction). ### result storage (`save_result` / `get_result` / `sweep_results`) @@ -200,6 +215,10 @@ none of them yet. platform), a row gets added here *before* it is assumed into a scope decision — the same discipline as alkblobs' requirements.md ("when a consumer fact changes, it changes here first"). -- Absence of evidence is marked, not overruled: streams/rate-limits/ +- Absence of evidence is marked, not overruled: rate limits and result storage stay on the list with their flags visible, per the - working posture, rather than being cut by this document alone. \ No newline at end of file + working posture, rather than being cut by this document alone. + Corrections run the other way too: an operator-authority record (the + 2026-10-04 streams correction) upgrades a row without waiting for a + consumer document to grow one — recorded here first, per the + requirements-change convention. \ No newline at end of file diff --git a/docs/research/phase-0.md b/docs/research/phase-0.md index 5cde4cd..93a331b 100644 --- a/docs/research/phase-0.md +++ b/docs/research/phase-0.md @@ -2,7 +2,8 @@ status: draft last_updated: 2026-10-04 (consumer inventory landed — OQ-ST-01 answered per-feature from the paused consumers' documents; OQ-ST-02/07 -sharpened; phase-0 plan step 1 done. Interface finding and driver +sharpened; phase-0 plan step 1 done; streams upgraded to in-scope by +operator-authority record same day. Interface finding and driver tension from 2026-10-03 remain trusted-but-unverified working input.) --- @@ -320,7 +321,12 @@ OQ-FS-05 writer coordination); queues and the outbox helper are documented needs (alkfs sync/fetch-on-miss outbox; alkblobs embedder-owned maintenance cadence); the scheduler is documented-thin (the family-wide "who sweeps/renews/reaps" problem, possibly collapsing -into queues); streams, rate limits, and result storage have **no +into queues); streams was upgraded by an operator-authority record +(the 2026-10-04 correction to the inventory's initial read: +type-filtered event watching from several places — repo-change +subscriptions in a git app, cross-app event watching — a reactivity +requirement notify cannot serve honestly, being fire-and-forget); +rate limits and result storage have **no named consumer** — carried per the keep-until-implementation posture with cut-flags visible, cut later rather than silently included. @@ -387,11 +393,12 @@ point — the question decomposes into contract-pinning rather than shape-invention: - Which parts of the honker-rs surface become the crate's *contract*: - the `notify`/`listen` pair, the queue claim/ack/visibility model, - locks, outbox, scheduler — all now have named consumers (inventory); - the stream/offset/consumer model does not (streams is keep-with-flag) - and rate-limits have an in-crate alternative mechanism (alkgit's wire - layer) — subset, renamed/regrouped, decided against the inventory + the `notify`/`listen` pair, the stream/offset/consumer model (in + scope per the inventory — subscriptions are the durable reactivity + half notify can't serve), the queue claim/ack/visibility model, + locks, outbox, scheduler — all have named consumers now; rate-limits + have an in-crate alternative mechanism (alkgit's wire layer) — + subset, renamed/regrouped, decided against the inventory rows rather than against the whole honker menu. - What is the delivery-guarantee contract, per mechanism (honker's own guide table shows how easily per-binding auto-checkpoint vs