SOW-0153: Go stability guide links to the install guide; Rust writer-state APIs named

.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;

.agents/sow/pending/SOW-0153-20261007-consumer-docs-release-clarity.md → .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,14 +150,18 @@ 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
 
 - No user design decision has been requested during publication, because this
   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
 

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

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.

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

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