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

3.5 KiB

Raw Blame History

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, ADR-004 — the per-engine driver decisions applying this posture.
OQ-06 (docs/architecture/open-questions.md) — the quality-read tracker.

3.5 KiB Raw Blame History