glm-5.3-flash
4391f6e879
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.
70 lines
3.5 KiB
Markdown
70 lines
3.5 KiB
Markdown
# ADR-005: Dependency ownership — published libraries by default, named fork triggers
|
|
|
|
## Status
|
|
|
|
Accepted (posture); fork triggers are live assessments tracked in OQ-06
|
|
|
|
## Context
|
|
|
|
The crate's reactive machinery sits on third-party work: honker
|
|
(SQLite side) and, conceptually, pgboss-rs (Postgres queue family).
|
|
Neither is adopted-by-adjacency — per guiding principle 3, ownership of
|
|
each subsystem is a deliberate per-question decision. The workspace
|
|
precedent is the targeted fork (alksocks' fast-socks5 extraction), but
|
|
a fork is expensive (especially when the forked code is sync and the
|
|
family standard is tokio — a fork of honker-rs is already a serious
|
|
port).
|
|
|
|
Two POCs (2026-10-04) measured the relevant postures per subsystem;
|
|
each carries its own record. This ADR fixes the *default calculus* and
|
|
the per-subsystem resolutions so Phase 1 design work starts from
|
|
stable ground.
|
|
|
|
## Decision
|
|
|
|
**Default posture: consume published libraries.** Fork or vendor only
|
|
when a named trigger fires. Per subsystem:
|
|
|
|
| Subsystem | Posture | Notes |
|
|
|---|---|---|
|
|
| honker-core (SQLite engine machinery) | published library, `honker-core = 0.5` | Fork trigger: the Phase 1 quality read of the watcher/transactional core finds a defect, OR a needed change upstream won't take. OQ-06 tracks the read. |
|
|
| rusqlite | published, riding honker-core's pin | Pin movement is honker-core's; we ride it ([ADR-003]). |
|
|
| tokio-postgres + deadpool-postgres | published library, as-is | Clean, zero conflicts, actively maintained (POC #2). |
|
|
| postgres-notify | **not adopted** (derive-not-adopt) | Lazy reconnect, connect_script skipped at initial connect, unquoted-identifier LISTENs, single maintainer. Hand-rolled forwarder instead ([ADR-004]). Fallback if upstream improves materially. |
|
|
| pg-boss queue machinery (pgboss-rs / node pg-boss) | **re-derived** on our driver; schema family as *design reference* only | pgboss-rs brings sqlx (second driver per binary) and has no LISTEN/NOTIFY (verified); the push half is ours either way, so queue-machinery reuse value is the honest comparison point and it loses on that arithmetic. Semantics depth: [queues.md], OQ-05. |
|
|
| honker-rs interface shape | **design reference**, not a dependency | Sync-only (no tokio); the surface is prior art for contract pinning ([ADR-006]), not code to ship. |
|
|
|
|
If any fork fires, forking is normal work we own (license/provenance
|
|
recorded per AGENTS.md §3 at adoption time) — it is not an exception
|
|
to this posture.
|
|
|
|
## Consequences
|
|
|
|
**Positive**
|
|
|
|
- Zero vendored code in the tree by default; upgrades are
|
|
`cargo update` work, not patch-management work.
|
|
- The fork triggers are concrete and named *before* the quality read,
|
|
so the read produces a decision, not a debate.
|
|
- Per-subsystem votes are recorded with evidence, so no future
|
|
discussion re-litigates from scratch.
|
|
|
|
**Negative**
|
|
|
|
- honker-core 0.5 remains alpha-quality software per its own README in
|
|
the link graph; the quality read (OQ-06) is the mitigation gate.
|
|
- The pg queue machinery is written by us — the pg-boss family's
|
|
battle-tested edge cases must be re-earned by design + tests
|
|
([queues.md]).
|
|
|
|
## References
|
|
|
|
- `docs/research/poc-sqlite-posture-findings.md` §"What feeds where"
|
|
(posture votes), `docs/research/poc-pg-posture-findings.md`
|
|
§"Dependency postures".
|
|
- OQ-ST-05, OQ-ST-06 (`docs/research/phase-0.md`) — the resolution
|
|
records.
|
|
- [ADR-003](003-sqlite-driver.md), [ADR-004](004-postgres-driver.md) —
|
|
the per-engine driver decisions applying this posture.
|
|
- OQ-06 (`docs/architecture/open-questions.md`) — the quality-read
|
|
tracker. |