0 Fork 0

Files

T

glm-5.3-flash 4391f6e879 docs: open Phase 1 — architecture spec set over the Phase 0 evidence

docs/architecture/ now exists: README index, overview, five component
specs (core-contract, engine-sqlite, engine-postgres, queues,
deployment), ADR-001..007 carrying the Phase 0 resolved decisions
(crate split, feature scope, per-engine drivers, dependency
ownership, wake contract, tx seam), and the centralized
open-questions tracker promotion: OQ-ST-01..08 mirror to OQ-01..08
one-to-one with statuses/resolutions carried; new Phase 1 questions
append (OQ-09 scheduler collapse, OQ-10 contract versioning).
Open Phase 1 work: OQ-04 contract pinning (high), OQ-05 queue
semantics depth (high), OQ-06 honker-core quality read (high;
fork-trigger gate), OQ-08 capability surface, OQ-09, OQ-10.

Erratum fixed in phase-0 OQ-ST-04 (thread-affinity friction is
SQLite-side, previously garbled as pg-side) and a stale scheduler-
boundary pointer corrected in consumer-inventory.md. Two review
passes run (findings: OQ-promotion numbering faithfulness, ADR
back-reference sync) — all critical/warning findings resolved.

2026-10-04 18:13:10 +00:00

4.1 KiB

Raw Blame History

ADR-002: Feature scope — what the store surface includes

Status

Accepted

Context

Honker's full surface (the interface prior art) covers nine feature families: notify/listen, streams, queues, scheduler, outbox, named locks, rate limits, result storage, and loadable-extension serving. The crate must decide which of these it ships, and the evidence-first answer (docs/research/consumer-inventory.md, 2026-10-04) grades each row by whether any consumer document actually names a need. This ADR fixes that scope so contract work isn't done against features no consumer wants.

Decision

In scope, first-class (a named consumer is pinned or the operator has recorded the need):

notify / listen — the transactional fire-and-forget signal layer. Pinned (alkfs path-tree invalidation; the watch_fires_on_commit POC evidence) and documented (alkblobs fleet visibility).
streams — durable pub/sub with per-consumer offsets and replay-on-attach. Operator-authority record (2026-10-04, consumer-inventory.md): type-filtered event watching / repo-change subscriptions that notify cannot honestly serve (no replay, no durability).

In scope (documented need, thinner):

named locks — TTL coordination locks. Pinned (alkblobs fleet sweeper) and documented (alkfs writer coordination); alkgit's CAS has an alternative design a lock is allowed to replace but needn't.
queues — durable at-least-once work with the transactional enqueue shape. Documented (alkfs sync/fetch-on-miss outbox; alkblobs maintenance cadence).
outbox helper — a thin helper over queues (enqueue inside the business transaction + a delivery/consumption worker shape), not a separately-needed feature. Same evidence as queues.
scheduler — cron/@every enqueueing into named queues, leader-elected. Documented-thin; the family-wide "who sweeps/renews/reaps" need. May collapse into queues if design shows scheduler = queues + tick (tracked in OQ-09).

Cut-flag (no named consumer; not silently included):

rate limits — alkgit enforces budgets in its own wire layer; a store-level rate limit is not the proven mechanism. The row stays listed with its flag visible; cut at implementation time rather than carried on momentum. If a distributed (cross-process) rate-limit need materializes, it gets a consumer-inventory row first.
result storage (save_result/get_result/sweep_results) — adjacent-tooling shape, useful but named by no consumer. Same cut-flag treatment.

Out:

The loadable-extension surface — no consumer needs it; every identified consumer is in-process Rust attaching to its own connection (OQ-ST-07, resolved cut-only). Cut unless a consumer appears.
Honker's exclusion lines, inherited as out: workflow DAGs, task chains/chords, multi-writer replication, distributed (cross-machine) locking. They stay out unless a consumer document grows a row.

New consumers add a row to docs/research/consumer-inventory.md before being assumed into scope.

Consequences

Positive

The contract surface is small and every part of it has a nameable consumer — contract-pinning work isn't spent on speculative surface.
Scope honesty is mechanical: the inventory is the ledger, and the cut-flag rows keep their flags visible instead of being silently dropped or silently shipped.

Negative

Rate limits and result storage, if ever needed, require the consumer inventory + contract process first — no ad-hoc additions.
Cutting the extension surface narrows honker compatibility; any future non-Rust consumer of these SQLite files cannot use honker's extension (acceptable: none exists).

References

docs/research/consumer-inventory.md — per-feature evidence grades.
OQ-ST-01, OQ-ST-07 (docs/research/phase-0.md) — resolved by this evidence; promoted as OQ-01 and OQ-07 in docs/architecture/open-questions.md.
core-contract.md — the trait surface this scope defines.
ADR-007 — the transactional property all in-scope enqueue/publish/notify features lean on.

4.1 KiB Raw Blame History