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:
glm-5.3-flash committed 2026-10-04 18:13:10 +00:00
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.