diff --git a/.agents/sow/SOW-status.md b/.agents/sow/SOW-status.md index f1423b58..c2f31a3e 100644 --- a/.agents/sow/SOW-status.md +++ b/.agents/sow/SOW-status.md @@ -15,7 +15,7 @@ order; the user may reorder it. tracked by SOW-0166, SOW-0167, SOW-0168). 4. SOW-0097 - Go duplication debt. 5. SOW-0098 - Rust legacy core / `jf` duplication debt (feeds SOW-0162). -6. SOW-0153 - Consumer docs release clarity. +6. SOW-0153 - Consumer docs release clarity (completed 2026-11-01). 7. SOW-0125 - Netdata filter operators (needs design decisions first). 8. SOW-0162 - Publishable C reader crate. 9. SOW-0169 - Pin the stock journalctl oracle in interoperability matrices @@ -57,8 +57,6 @@ None. (cheap polling first). - 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-0162 - Publishable C Reader Crate: new, 2026-10-31. - SOW-0163 - v0.11.0 Release: new, 2026-10-31. - SOW-0164 - Netdata SDK-Exclusive Adoption And Vendored Journal Removal: @@ -89,6 +87,7 @@ None. read and continue every file earlier releases wrote. Follow-ups: SOW-0171, SOW-0172. +- 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 65% 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..42413d67 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 +approved by the user 2026-11-03. ## Requirements @@ -78,7 +77,8 @@ Risks: ## Pre-Implementation Gate -Status: needs-user-decision +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 @@ -158,6 +158,10 @@ 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. +- 2026-11-03 (user): decision 1A approved. ## Plan @@ -169,13 +173,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, approved by the + user 2026-11-03) 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: @@ -201,81 +205,117 @@ 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: -- 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`); `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` + 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. +- `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: -- 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: +Reviewer findings (self-review; tests are the gate, no external reviewers): -- Deepseek's stale Go version claim and GLM's thin Rust state-query wording - are tracked here; neither was a release-blocking runtime finding. +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` (`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: -- 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` + 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: -- 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. +- 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`. +- 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: -- Existing SDK behavior has not changed; any installation reference impact - will be checked during implementation. +- None needed (see the artifact maintenance gate). Project skills update: -- No release-scan policy change has been approved. +- None needed. End-user/operator docs update: -- The two identified passages are pending; no docs change is claimed. +- `go/API.md`, `docs/Writer-APIs.md`, `docs/Indexed-Snapshots.md`. End-user/operator skills update: -- None exist in this repository. +- None exist. Lessons: -- Release-version prose can become stale even when executable installation - declarations are consistent. +- See Lessons Extracted. Follow-up mapping: -- Both confirmed documentation findings are assigned to this pending SOW. +- None remain; both findings are implemented. + +Audit: + +- `.agents/sow/audit.sh`: SOW initialization complete and clean. ## 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 cc761c26..d16529ae 100644 --- a/SOW-status.md +++ b/SOW-status.md @@ -15,9 +15,6 @@ is `.agents/sow/SOW-status.md`; if summaries differ, the canonical ledger wins. - SOW-0160 - Go XZ Reader Dictionary Allocation: open, not activated. Analysis done; the cost is the Go writer's 8 MiB declared XZ dictionary. No redesign or implementation is authorized until user decision D1. -- `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. @@ -31,8 +28,8 @@ is `.agents/sow/SOW-status.md`; if summaries differ, the canonical ledger wins. ## Done -- SOW-0045, SOW-0071, SOW-0122, SOW-0123, SOW-0137 and SOW-0161: completed - 2026-11-01; details in the canonical ledger. +- SOW-0045, SOW-0071, SOW-0122, SOW-0123, SOW-0137, SOW-0153 and SOW-0161: + completed 2026-11-01; details in the canonical ledger. - SOW-0121 - File-Backed Journalctl Full Parity And Ship Decision: completed. Directional cursor integration and PR12 fixes pass three internal reviews, 3,514 native comparisons and146 portable controls. Pushed-head native CI is diff --git a/docs/Indexed-Snapshots.md b/docs/Indexed-Snapshots.md index 1adfaf3c..e271aa66 100644 --- a/docs/Indexed-Snapshots.md +++ b/docs/Indexed-Snapshots.md @@ -176,7 +176,10 @@ by earlier releases store it truncated. 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 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 74414e53..e86afa4e 100644 --- a/docs/Writer-APIs.md +++ b/docs/Writer-APIs.md @@ -109,7 +109,12 @@ 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. 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 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