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.
This commit is contained in:
1 parent
db73678090
commit
4391f6e879
17 files changed
+1812
-14
No files matched your search
@@ -0,0 +1,99 @@
|
||||
# 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](../core-contract.md) — the trait surface this
|
||||
scope defines.
|
||||
- [ADR-007](007-transactional-seam.md) — the transactional property all
|
||||
in-scope enqueue/publish/notify features lean on.
|
||||
Reference in new issue
Block a user