From 4a16f0df317cdfe1924ad8a84fb3f4263a2a5e67 Mon Sep 17 00:00:00 2001 From: Costa Tsaousis Date: Sun, 1 Nov 2026 21:04:31 +0000 Subject: [PATCH 1/5] Point Go stability guide at the install guide; name Rust writer-state APIs go/API.md named a stale go/v0.3.0 tag; it now links to go/README.md. The writer docs name JournalError::WriterPoisoned and is_poisoned() beside Go's ErrWriterFailed. --- .agents/sow/SOW-status.md | 5 +- ...-20261007-consumer-docs-release-clarity.md | 82 ++++++++----------- SOW-status.md | 7 +- docs/Indexed-Snapshots.md | 4 +- docs/Writer-APIs.md | 4 +- go/API.md | 4 +- 6 files changed, 44 insertions(+), 62 deletions(-) rename .agents/sow/{pending => done}/SOW-0153-20261007-consumer-docs-release-clarity.md (79%) diff --git a/.agents/sow/SOW-status.md b/.agents/sow/SOW-status.md index 44ee8da3..693114ea 100644 --- a/.agents/sow/SOW-status.md +++ b/.agents/sow/SOW-status.md @@ -15,7 +15,7 @@ order; the user may reorder it. gaps tracked by SOW-0166, SOW-0167, SOW-0168). 5. SOW-0097 - Go duplication debt. 6. SOW-0098 - Rust legacy core / `jf` duplication debt (feeds SOW-0162). -7. SOW-0153 - Consumer docs release clarity. +7. SOW-0153 - Consumer docs release clarity (completed 2026-11-01). 8. SOW-0125 - Netdata filter operators (needs design decisions first). 9. SOW-0162 - Publishable C reader crate. 10. SOW-0163 - v0.11.0 release. @@ -44,8 +44,6 @@ order; the user may reorder it. cost; needs a user decision. - SOW-0125 - Netdata Filter Operators Gap Analysis: feature analysis; needs semantic decisions before implementation. -- SOW-0153 - Consumer Documentation Release Clarity: stale `go/v0.3.0` text and - Rust writer-state discoverability. - SOW-0160 - Go XZ Reader Dictionary Allocation: cost is the Go writer's 8 MiB declared dictionary; decision D1 (writer dictionary size) pending. - SOW-0162 - Publishable C Reader Crate: new, 2026-10-31. @@ -57,6 +55,7 @@ order; the user may reorder it. ## Recently Closed Or Completed +- SOW-0153 - Consumer Documentation Release Clarity: completed 2026-11-01. - SOW-0122 - Journalctl Performance Followups: completed 2026-11-01; `--list-invocations` 8-120x faster and IDX alignment matches stock. - SOW-0161 - File Indexer Source Posting Membership: completed 2026-11-01; diff --git a/.agents/sow/pending/SOW-0153-20261007-consumer-docs-release-clarity.md b/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md similarity index 79% rename from .agents/sow/pending/SOW-0153-20261007-consumer-docs-release-clarity.md rename to .agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md index 1f5777bd..5ba0e858 100644 --- a/.agents/sow/pending/SOW-0153-20261007-consumer-docs-release-clarity.md +++ b/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md @@ -2,11 +2,10 @@ ## Status -Status: open +Status: completed -Sub-state: Two non-blocking documentation findings from SOW-0151 review are -tracked. No implementation is authorized or started; choose the documentation -approach before changing consumer guidance. +Sub-state: completed 2026-11-01 in the autonomous backlog run; decision 1A is +agent-chosen, pending user review (PR body). ## Requirements @@ -78,7 +77,8 @@ Risks: ## Pre-Implementation Gate -Status: needs-user-decision +Status: passed 2026-11-01 with decision 1A (agent-chosen, see Implications And +Decisions). Problem / root-cause model: @@ -158,6 +158,9 @@ Open decisions: documentation follow-up is independent and does not block the release. - Recommend decision 1A when this SOW is activated; record the actual selection before implementation. +- 2026-11-01: decision 1A applied as agent-chosen, pending user review (the + user authorized autonomous low-risk choices flagged in PRs): `go/API.md` + links to `go/README.md` for the current release instead of naming a tag. ## Plan @@ -205,77 +208,58 @@ Failure handling: Acceptance criteria evidence: -- The cited current passages establish the problem; implementation acceptance - has not been evaluated because the approach remains unselected. +- `go/API.md` no longer names a version; it states the `go/vX.Y.Z` tag form + and links to `go/README.md`, which carries the install command + (`go/README.md:9`) and is checked by `tests/release/release.py`. +- `docs/Writer-APIs.md` names Rust `JournalError::WriterPoisoned`, + `JournalWriter::is_poisoned()` and `Log::is_poisoned()` beside Go + `ErrWriterFailed`; verified against `journal-core` `writer.rs:281,439,524` + and `journal-log-writer` `log/mod.rs:116,127`. Tests or equivalent validation: -- Read-only passage and API inspection completed. Documentation checks belong - to the eventual implementation and have not been claimed here. +- `python3 tests/docs/check_wiki_docs.py`: 16 files validated. +- `git diff --check`: clean. No code examples changed, so + `verify_examples.py` has nothing new to compile. Real-use evidence: -- The stale tag is visible in the Go stability document; existing state-query - names were checked directly in public Rust source. +- Links and API names checked by reading the targets. Reviewer findings: -- Deepseek's stale Go version claim and GLM's thin Rust state-query wording - are tracked here; neither was a release-blocking runtime finding. +- Own review; no external reviewers. Same-failure scan: -- Full active consumer prose scanning is part of the implementation plan, - after the user selects the maintenance approach. +- `grep -rn "go/v0\.[0-9]"` over active Markdown outside SOW records and the + status ledger: no other stale version claim. `docs/Indexed-Snapshots.md:176` + had the same vague Rust wording ("its failed-writer error"); fixed to name + `JournalError::WriterPoisoned` and `is_poisoned()`. Sensitive data gate: -- This record uses only public API names, release commits and relative paths. +- Public API names and repository paths only. Artifact maintenance gate: -- AGENTS.md, runtime skills and specs have no implemented changes. -- Consumer docs remain unchanged; no output/reference skills exist. -- This SOW is open in pending; both ledgers record it. Full close-out artifact - evidence will be added after the authorized implementation. - -Specs update: - -- Existing SDK behavior has not changed; any installation reference impact - will be checked during implementation. - -Project skills update: - -- No release-scan policy change has been approved. - -End-user/operator docs update: - -- The two identified passages are pending; no docs change is claimed. - -End-user/operator skills update: - -- None exist in this repository. - -Lessons: - -- Release-version prose can become stale even when executable installation - declarations are consistent. - -Follow-up mapping: - -- Both confirmed documentation findings are assigned to this pending SOW. +- AGENTS.md, project skills and specs: no change; documentation-only fix. +- End-user docs: `go/API.md`, `docs/Writer-APIs.md`, + `docs/Indexed-Snapshots.md`. +- Status indexes updated. ## Outcome -Open; design selection and implementation have not started. +Completed. The Go stability guide defers versions to the install guide, and +the writer docs name the Rust state queries beside Go's error. ## Lessons Extracted -- Prefer one authoritative version guide when the user selects that approach. +- Prefer one authoritative version guide; other pages link to it. ## Followup -- The two findings are the work of this SOW; no further item is deferred. +- None. ## Regression Log diff --git a/SOW-status.md b/SOW-status.md index 740f2e7a..5b27018a 100644 --- a/SOW-status.md +++ b/SOW-status.md @@ -10,16 +10,13 @@ is `.agents/sow/SOW-status.md`; if summaries differ, the canonical ledger wins. - SOW-0156 - Fixed-Header Consistency Audit: paused; audit done, Rust parity gaps fixed, user decisions D1-D6 pending. -SOW-0045, SOW-0071, SOW-0122, SOW-0123, SOW-0137 and SOW-0161 completed on -2026-11-01. +SOW-0045, SOW-0071, SOW-0122, SOW-0123, SOW-0137, SOW-0153 and SOW-0161 +completed on 2026-11-01. ## Pending - SOW-0160 - Go XZ Reader Dictionary Allocation: analysis done; the cost is the Go writer's 8 MiB declared XZ dictionary. User decision D1 pending. -- `SOW-0153-20261007-consumer-docs-release-clarity.md` - open. Tracks stale Go - consumable-version prose and Rust writer-state method discoverability; - documentation design and implementation remain unapproved. - `SOW-0125-20260625-netdata-filter-operators-gap-analysis.md` - open, parked by user decision on 2026-06-25. Preserves string/numeric operator support matrix and semantic decisions; not executable until explicitly resumed. diff --git a/docs/Indexed-Snapshots.md b/docs/Indexed-Snapshots.md index 892aed24..dbe4db13 100644 --- a/docs/Indexed-Snapshots.md +++ b/docs/Indexed-Snapshots.md @@ -173,7 +173,7 @@ do not replace strict verification of an uncertain file's complete graph. After an uncertain mutating failure, writers reject further mutation and close only resources, without publishing clean metadata or deleting an empty-looking -file. Go exposes `ErrWriterFailed`, preserving the original error; Rust exposes -its failed-writer error. Pre-mutation validation failures do not poison a writer. +file. Go exposes `ErrWriterFailed`, preserving the original error; Rust returns +`JournalError::WriterPoisoned` and reports the state through `is_poisoned()`. Pre-mutation validation failures do not poison a writer. No automatic repair, deletion or replay is part of strict verification. See [[Writer-APIs|Writer APIs]] for lifecycle and durability choices. diff --git a/docs/Writer-APIs.md b/docs/Writer-APIs.md index e167e505..3507ef82 100644 --- a/docs/Writer-APIs.md +++ b/docs/Writer-APIs.md @@ -63,7 +63,9 @@ A mutating append, sync or archive failure poisons the writer. Further mutation is rejected. Close/drop releases resources without rewriting metadata, applying retention or deleting an uncertain file, including a failed first append whose cached entry count is zero. Pre-mutation input validation errors remain reusable. -Go exposes `ErrWriterFailed` and preserves the original cause. +Go exposes `ErrWriterFailed` and preserves the original cause. Rust rejects +later mutations with `JournalError::WriterPoisoned`, and `JournalWriter::is_poisoned()` +and `Log::is_poisoned()` report the state without attempting a mutation. Append-open validates supported format metadata; it does not certify the full native index graph. Before a `Writer` or `Log` can reuse uncertain files, exclude diff --git a/go/API.md b/go/API.md index d53067f9..2ea0d497 100644 --- a/go/API.md +++ b/go/API.md @@ -6,8 +6,8 @@ This module is imported as: import "github.com/netdata/systemd-journal-sdk/go/journal" ``` -The current consumable tag for this subdirectory module is expected to be -`go/v0.3.0`. +Tags for this subdirectory module use the `go/vX.Y.Z` form; the current release +and installation command are in [`README.md`](README.md). ## Stability Contract From d3eeb42810f120d52d5bac206ae6beb829fd117f Mon Sep 17 00:00:00 2001 From: Costa Tsaousis Date: Sun, 1 Nov 2026 21:18:15 +0000 Subject: [PATCH 2/5] Say Rust returns WriterPoisoned on later mutations and Log wraps it; complete SOW-0153 validation records --- ...-20261007-consumer-docs-release-clarity.md | 74 ++++++++++++++++--- docs/Indexed-Snapshots.md | 7 +- docs/Writer-APIs.md | 7 +- 3 files changed, 72 insertions(+), 16 deletions(-) diff --git a/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md b/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md index 5ba0e858..35b1494d 100644 --- a/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md +++ b/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md @@ -172,13 +172,13 @@ Open decisions: Implementation: -- The project manager implements after user selection; no changes to consumer - documentation have been made under this SOW. +- The project manager implemented decision 1A (agent-chosen, pending user + review) on 2026-11-01; see Validation. Reviewers: -- The initial findings are independently confirmed. Apply the current - external-review authorization rules at the whole-SOW review milestone. +- Whole-SOW self-review after local validation; tests are the gate. External + reviewers are not used. Repository boundary block for every external-reviewer prompt: @@ -204,6 +204,14 @@ Failure handling: - Created a pending tracking record from the project-local SOW template for two confirmed P3 findings. Publication source and consumer docs are unchanged. +### 2026-11-01 + +- Applied decision 1A and the Rust writer-state wording; validated; closed. +- PR review: Rust wording refined to say the failing call returns its own + error, later mutation attempts return `JournalError::WriterPoisoned`, and + `Log` wraps it as `WriterError::Journal` (verified at `journal-core` + `writer.rs:629-636` and `journal-log-writer` `error.rs:44`). + ## Validation Acceptance criteria evidence: @@ -226,16 +234,23 @@ Real-use evidence: - Links and API names checked by reading the targets. -Reviewer findings: +Reviewer findings (self-review; tests are the gate, no external reviewers): -- Own review; no external reviewers. +1. The first wording implied `WriterPoisoned` is the error of the failing + call and named it without `Log`'s `WriterError::Journal` wrapper. + Disposition: fixed in both pages (raised in PR review, confirmed against + the code above). +2. `go/API.md` now depends on `go/README.md` staying current. Disposition: + accepted; `tests/release/release.py` checks the README install command at + release time. Same-failure scan: - `grep -rn "go/v0\.[0-9]"` over active Markdown outside SOW records and the - status ledger: no other stale version claim. `docs/Indexed-Snapshots.md:176` - had the same vague Rust wording ("its failed-writer error"); fixed to name - `JournalError::WriterPoisoned` and `is_poisoned()`. + status ledger: no other stale version claim. `docs/Indexed-Snapshots.md` + had the same vague Rust wording ("its failed-writer error"); fixed. +- `grep -n "WriterPoisoned" docs/*.md`: `docs/Rust-API.md` only lists the + variant in its semver notes; no shape claim to fix. Sensitive data gate: @@ -243,10 +258,45 @@ Sensitive data gate: Artifact maintenance gate: -- AGENTS.md, project skills and specs: no change; documentation-only fix. -- End-user docs: `go/API.md`, `docs/Writer-APIs.md`, +- AGENTS.md: no change; documentation-only fix with no workflow rule. +- Runtime project skills: `project-docs-authoring` rules were followed; + no new rule. +- Specs: no change; the specs describe writer poisoning behavior, which did + not change. +- End-user/operator docs: `go/API.md`, `docs/Writer-APIs.md`, `docs/Indexed-Snapshots.md`. -- Status indexes updated. +- End-user/operator skills: none exist. +- SOW lifecycle: `Status: completed` and the move to `done/` are committed + with the documentation change. +- SOW-status.md: canonical ledger and root index updated. + +Specs update: + +- None needed (see the artifact maintenance gate). + +Project skills update: + +- None needed. + +End-user/operator docs update: + +- `go/API.md`, `docs/Writer-APIs.md`, `docs/Indexed-Snapshots.md`. + +End-user/operator skills update: + +- None exist. + +Lessons: + +- See Lessons Extracted. + +Follow-up mapping: + +- None remain; both findings are implemented. + +Audit: + +- `.agents/sow/audit.sh`: SOW initialization complete and clean. ## Outcome diff --git a/docs/Indexed-Snapshots.md b/docs/Indexed-Snapshots.md index dbe4db13..bdad0e03 100644 --- a/docs/Indexed-Snapshots.md +++ b/docs/Indexed-Snapshots.md @@ -173,7 +173,10 @@ do not replace strict verification of an uncertain file's complete graph. After an uncertain mutating failure, writers reject further mutation and close only resources, without publishing clean metadata or deleting an empty-looking -file. Go exposes `ErrWriterFailed`, preserving the original error; Rust returns -`JournalError::WriterPoisoned` and reports the state through `is_poisoned()`. Pre-mutation validation failures do not poison a writer. +file. Go exposes `ErrWriterFailed`, preserving the original error. Rust returns the +original error from the failing call and `JournalError::WriterPoisoned` on later +mutation attempts (wrapped as `WriterError::Journal` by `Log`), and reports the +state through `is_poisoned()`. Pre-mutation validation failures do not poison a +writer. No automatic repair, deletion or replay is part of strict verification. See [[Writer-APIs|Writer APIs]] for lifecycle and durability choices. diff --git a/docs/Writer-APIs.md b/docs/Writer-APIs.md index 3507ef82..42dc4a2e 100644 --- a/docs/Writer-APIs.md +++ b/docs/Writer-APIs.md @@ -63,8 +63,11 @@ A mutating append, sync or archive failure poisons the writer. Further mutation is rejected. Close/drop releases resources without rewriting metadata, applying retention or deleting an uncertain file, including a failed first append whose cached entry count is zero. Pre-mutation input validation errors remain reusable. -Go exposes `ErrWriterFailed` and preserves the original cause. Rust rejects -later mutations with `JournalError::WriterPoisoned`, and `JournalWriter::is_poisoned()` +Go exposes `ErrWriterFailed` and preserves the original cause. In Rust the +failing call returns its own error; keep it, because later mutation attempts +return only `JournalError::WriterPoisoned`. The low-level `JournalWriter` +returns that variant directly, and `Log` wraps it as +`WriterError::Journal(JournalError::WriterPoisoned)`. `JournalWriter::is_poisoned()` and `Log::is_poisoned()` report the state without attempting a mutation. Append-open validates supported format metadata; it does not certify the full From 133535fc332d47fc7669232f85d8ce9374c0d25b Mon Sep 17 00:00:00 2001 From: Costa Tsaousis Date: Tue, 3 Nov 2026 07:14:29 +0000 Subject: [PATCH 3/5] Record the user approval for SOW-0153 decision 1A --- ...0153-20261007-consumer-docs-release-clarity.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md b/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md index 35b1494d..46d38b18 100644 --- a/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md +++ b/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md @@ -4,8 +4,8 @@ Status: completed -Sub-state: completed 2026-11-01 in the autonomous backlog run; decision 1A is -agent-chosen, pending user review (PR body). +Sub-state: completed 2026-11-01 in the autonomous backlog run; decision 1A +approved by the user 2026-11-03. ## Requirements @@ -77,8 +77,8 @@ Risks: ## Pre-Implementation Gate -Status: passed 2026-11-01 with decision 1A (agent-chosen, see Implications And -Decisions). +Status: passed 2026-11-01 with decision 1A (approved by the user 2026-11-03, +see Implications And Decisions). Problem / root-cause model: @@ -150,7 +150,7 @@ Open decisions: - Decision 1: B, surgical: update the explicit Go version and document the existing writer-state APIs. This changes little prose but retains a version statement that future releases must update. -- Neither option is approved or implemented by creating this tracking record. +- Resolved: 1A, approved by the user 2026-11-03. ## Implications And Decisions @@ -161,6 +161,7 @@ Open decisions: - 2026-11-01: decision 1A applied as agent-chosen, pending user review (the user authorized autonomous low-risk choices flagged in PRs): `go/API.md` links to `go/README.md` for the current release instead of naming a tag. +- 2026-11-03 (user): decision 1A approved. ## Plan @@ -172,8 +173,8 @@ Open decisions: Implementation: -- The project manager implemented decision 1A (agent-chosen, pending user - review) on 2026-11-01; see Validation. +- The project manager implemented decision 1A (agent-chosen, approved by the + user 2026-11-03) on 2026-11-01; see Validation. Reviewers: From ea12b266b9cd0d100f272cf5feb97949d44cbab4 Mon Sep 17 00:00:00 2001 From: Costa Tsaousis Date: Tue, 3 Nov 2026 07:16:59 +0000 Subject: [PATCH 4/5] Record the docs example run and the exact release check for SOW-0153 --- ...0153-20261007-consumer-docs-release-clarity.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md b/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md index 46d38b18..42413d67 100644 --- a/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md +++ b/.agents/sow/done/SOW-0153-20261007-consumer-docs-release-clarity.md @@ -219,7 +219,8 @@ Acceptance criteria evidence: - `go/API.md` no longer names a version; it states the `go/vX.Y.Z` tag form and links to `go/README.md`, which carries the install command - (`go/README.md:9`) and is checked by `tests/release/release.py`. + (`go/README.md:9`); `tests/release/release.py` `validate_install_examples` + fails a release when that reference names another version. - `docs/Writer-APIs.md` names Rust `JournalError::WriterPoisoned`, `JournalWriter::is_poisoned()` and `Log::is_poisoned()` beside Go `ErrWriterFailed`; verified against `journal-core` `writer.rs:281,439,524` @@ -228,8 +229,10 @@ Acceptance criteria evidence: Tests or equivalent validation: - `python3 tests/docs/check_wiki_docs.py`: 16 files validated. -- `git diff --check`: clean. No code examples changed, so - `verify_examples.py` has nothing new to compile. +- `git diff --check`: clean. +- `python3 tests/docs/verify_examples.py` (2026-11-03, caches under + `.local/`): all 35 examples pass (19 Go, 16 Rust). No example changed in + this SOW; the run confirms the edited pages still build. Real-use evidence: @@ -242,8 +245,10 @@ Reviewer findings (self-review; tests are the gate, no external reviewers): Disposition: fixed in both pages (raised in PR review, confirmed against the code above). 2. `go/API.md` now depends on `go/README.md` staying current. Disposition: - accepted; `tests/release/release.py` checks the README install command at - release time. + accepted. `tests/release/release.py` (`validate_install_examples`) fails a + release when a versioned module reference in `go/README.md` names a + different version; it does not require the install command to exist, so + removing that command would not be caught. Same-failure scan: From b17d76ced15b69ec920bc5fe3a0cbf733f176cff Mon Sep 17 00:00:00 2001 From: Costa Tsaousis Date: Wed, 4 Nov 2026 22:05:08 +0000 Subject: [PATCH 5/5] Restore SOW ledger entries lost in the stack merge --- .agents/sow/SOW-status.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.agents/sow/SOW-status.md b/.agents/sow/SOW-status.md index 84192f81..44d01094 100644 --- a/.agents/sow/SOW-status.md +++ b/.agents/sow/SOW-status.md @@ -75,6 +75,9 @@ None. ## Recently Closed Or Completed +- SOW-0160 - Go XZ Reader Dictionary Allocation: completed 2026-11-04. The Go + writer declares a 256 KiB XZ dictionary like Rust; Go and Rust reads of new + Go-written XZ files cost 5-10x less CPU. Stock journalctl is unaffected. - SOW-0156 - Fixed-Header Consistency Audit: completed 2026-11-03. Both SDKs apply systemd v260.1's writable-open header rules and timestamp ranges, keep