adopt the tracing log facade, engine crates only (review 004 item 7's family-level decision, ADR-025): the family precedent checked and unanimous (alkcall/alktunnels/alksocks/alktty all on tracing = "0.1" facade-only, tracing-subscriber env-filter a dev-dep where present, silent by default); user sign-off taken in-session (2026-10-11, adopt-tracing option chosen) and recorded in the ADR's status; core stays dep- and emit-free (the explicit core-dep answer — the payload serde deps remain the sole core deps, the ADR states the ADR-020-§4 reading explicitly); all 19 library-path eprintln! sites migrated to tracing::warn!/error! with message text + the alkstore: prefix + the secret-free discipline unchanged (17 at review time, +2 from the review's own inline tick/lease restructures — re-grepped, sqlite 10 / pg 9, zero remainder, tests' harness-skip prints untouched); levels: warn = retried/degraded ops, error = unrecoverable loss (watcher death, discarded pooled clients, panic-path rollback failures); the four substrate-lineage files ride PROVENANCE delta D-41 (message-identical macro swap); deployment.md gains the diagnostics-posture section (operator recipe RUST_LOG=warn/error at the consuming binary; listener application_name diagnosability joins it), ADR index + design-decisions table carry the 025 row, CHANGELOG's 0.1.0 body states the facade; pg-fix-forwarder-diagnosability's output form now pinned (warn on failed reconnect connects with attempt/backoff context, error on the loop-exit poll error); gates green: build, workspace tests server-less, clippy -D warnings, fmt, doc gate zero warnings, fuzz corpus replay 6/6; task -> completed

This commit is contained in:
glm-5.3-flash committed 2026-10-11 14:19:07 +00:00
1 parent ce5da852ca
commit a9b6cf0c86
19 files changed
+332 -31

No files matched your search

+69 -8
View File
@@ -1,7 +1,7 @@
---
id: decide-log-facade-adoption
name: Decide the log-facade posture (review 004 item 7, family-level)
status: pending
status: completed
depends_on: []
scope: narrow
risk: low
@@ -47,15 +47,15 @@ part of the record.
## Acceptance Criteria
- [ ] The family-precedent check is done and recorded (what
- [x] The family-precedent check is done and recorded (what
alkcall/alktunnels/alksocks/alktty do, if anything)
- [ ] The decision of record landed: ADR (adoption) or documented
- [x] The decision of record landed: ADR (adoption) or documented
posture (decline), with the rationale and the core-dep question
answered explicitly
- [ ] The 17 existing `eprintln!` sites' disposition under the
- [x] The 17 existing `eprintln!` sites' disposition under the
decision is named (migrated / kept / reduced)
- [ ] User sign-off recorded
- [ ] Doc gate green (whatever text landed)
- [x] User sign-off recorded
- [x] Doc gate green (whatever text landed)
## References
@@ -70,8 +70,69 @@ part of the record.
## Notes
> To be filled by implementation agent
> Decisions of record the description didn't pin:
- **The decision landed as ADR** ([ADR-025](../docs/architecture/decisions/025-log-facade.md)):
`tracing` adopted, **engine crates only**; core keeps its
dependency posture and stays emit-free — that is the explicit
core-dep answer. No subscriber dep anywhere in `[dependencies]`;
`tracing-subscriber` stays a `[dev-dependencies]` affair only if a
test ever needs to assert on emitted events (none does yet).
- **The user's sign-off was taken in-session via a choose-one
question** with the three options of the description plus the
family-precedent evidence table (recorded 2026-10-11; "Adopt
tracing" chosen). It is part of the ADR's §Status.
- **The site count moved under this task's feet**: the description
and the review carried 17; the re-grep at decision time found **19**
genuine library-path sites (sqlite 10, pg 9) — the delta came from
review 004's own inline fixes re-structuring the tick/lease failure
arms. The ADR records both numbers honestly; all 19 migrated, None
kept, None deleted.
- **The migration rode this task rather than a follow-up** — the
description's letter asked only for the disposition to be *named*,
but leaving 19 `eprintln!` sites next to a written adoption ADR
would have made the record aspirational and re-verified a stale
count later; the mechanical migration is small enough to land with
the decision (levels: `warn` = retried/degraded ops, `error` =
unrecoverable-loss events: watcher death, discarded pooled clients,
panic-path rollback failures).
- **Substrate-lineage sites** (8 of the sqlite 10 — `watcher.rs` ×6,
`schema.rs` ×1, `ops.rs` ×1; the other two are engine-owned
`tx.rs`) rode the PROVENANCE delta
discipline: register entry **D-41** (port delta) in
`alkstore-sqlite/src/substrate/PROVENANCE.md`, per ADR-018's
format; message text and the `alkstore:` prefix carried over
unchanged, only the macro swapped.
- **No consumer-inventory row** was required (ADR-017 §2's row-first
gate is on contract extensions; this touches no trait/type/error
surface — the ADR states that explicitly).
## Summary
> To be filled on completion
> The family-precedent check found all four repos (alkcall,
> alktunnels, alksocks, alktty) on `tracing = "0.1"` facade-only, with
> `tracing-subscriber` (env-filter) as a dev-dependency where it
> appears — silent by default. The user signed off on adopting
> tracing (2026-10-11, in-session question). The decision of record
> is ADR-025: `tracing` in the engine crates (`alkstore-sqlite`,
> `alkstore-postgres` gain the dep; core and mem stay dep- and
> emit-free), subscriber wiring on the consumer/binary, the
> secret-free rule promoted to standing law. The disposition landed
> with the decision: all 19 library-path `eprintln!` sites (17 at
> review time; +2 from the review's own inline fixes) migrated to
> `tracing::warn!/error!` with message text and secret-free
> discipline unchanged; the four substrate-lineage sites carry
> PROVENANCE delta D-41. deployment.md gained a "Diagnostics posture"
> section (operator recipe: `RUST_LOG=warn`/`error` at the consuming
> binary; silent-by-default honesty), the architecture README's ADR
> index and the design-decisions table gained the ADR-025 row, and
> the CHANGELOG's 0.1.0 body states the facade and the recipe.
> Verified: `cargo build`, `cargo test --workspace` (green,
> server-less), `cargo clippy --all-targets -- -D warnings`
> (clean), `cargo fmt --check` (clean), the doc gate
> (`RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --workspace`,
> zero warnings), the fuzz corpus replay (6/6). The consumer task
> `pg-fix-forwarder-diagnosability` now has its output form pinned:
> `tracing::warn!` on the failed reconnect connects (with
> attempt/backoff context), `tracing::error!` on the loop-exit poll
> error.