From b68435128be1e24b94fc7ec259d6e9093669fd99 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 5 Sep 2026 19:24:35 +0000 Subject: [PATCH] Document the v1.7.0 release --- docs/releases/v1.7.0.md | 100 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 docs/releases/v1.7.0.md diff --git a/docs/releases/v1.7.0.md b/docs/releases/v1.7.0.md new file mode 100644 index 0000000..f9934d9 --- /dev/null +++ b/docs/releases/v1.7.0.md @@ -0,0 +1,100 @@ +# Narratio v1.7.0 + +Narratio v1.7.0 completes the maintainability refactor begun after v1.6.0. It +simplifies filesystem and process handling, makes resumable work more precise, +replaces legacy local and remote state with explicit authorities, and turns +cleanup into the final ordinary pipeline stage. + +## Summary + +The session manifest is now the sole durable local progress ledger. Analyze +checkpoints successful artifacts individually, allowing an interrupted or +partially failed analysis to resume at the first incomplete artifact without +rerunning successful siblings unless forced. + +Remote publication now commits immutable run state before advancing one +verified current pointer. Publish locks are independent per-source objects; +locked outputs retain their previously committed declarations rather than +being overwritten or silently omitted. Local cleanup runs after notification +as a separately recorded, safely retryable stage. + +The release also adopts Go 1.26, simplifies ordinary file operations around +Narratio's trusted group-owned workspace model, improves subprocess lifecycle +handling, decomposes several large orchestration and validation components, +and removes mutable global test seams. + +## Compatibility + +This is a minor release with deliberate removal of compatibility paths that +were deprecated and documented as subject to removal: + +- Campaigns must use one versioned `narratio.party.v1` `party.yml`. Separate + players files, session-level party overrides, and unversioned party documents + are rejected. +- Session manifests must declare `schema_version: + narratio.session-manifest.v1` and satisfy the current strict schema. Older + unversioned state and manifests containing the retired + `post_publish_cleanup` obligation are rejected rather than migrated. +- Remote current state must be selected by + `current/commit-pointer.json` and its referenced immutable run commit. Legacy + current-state layouts are no longer inferred. +- The retired aggregate `locks.yml` object is ignored. Publish locks now live + as independent strict objects under the session lock prefix. +- Run manifests are no longer produced or consumed. The session manifest owns + durable stage progress; invocation summaries and run workspaces remain + operational data rather than a second progress authority. + +The CLI and current pipeline/configuration formats otherwise remain compatible. +Building and maintaining Narratio now requires Go 1.26. Cross-built Linux, +macOS, and Windows assets remain available for `amd64` and `arm64`. + +## Upgrade + +Before upgrading a campaign that still uses compatibility data: + +1. Replace legacy party/player inputs with the documented + [`narratio.party.v1`](../integrations/party.md) campaign roster. +2. If a local manifest contains an outstanding `post_publish_cleanup` + obligation, complete it with the pre-upgrade binary. Otherwise verify the + remote commit, move aside or regenerate the incompatible manifest, or + restore a verified committed snapshot. Do not migrate state by manually + editing JSON. +3. Republish sessions that do not yet have a valid immutable run commit and + `current/commit-pointer.json`; legacy remote layouts are not current state in + v1.7.0. +4. Recreate any required publication locks with `narratio session locks add`. + After verifying the new locks and publication behavior, the ignored legacy + `locks.yml` object may be removed manually. + +Existing compatible session manifests and already committed remote snapshots +need no special action. Consult [Operations](../operations.md) and +[Troubleshooting](../troubleshooting.md) for recovery procedures. + +## Changes + +- Upgraded the maintained development and release baseline to Go 1.26. +- Reworked subprocess execution and Windows process-tree supervision while + preserving contextual wait and cleanup failures. +- Replaced custom confined ordinary I/O and directory-promotion machinery with + simpler standard-library operations while retaining bounded reads, atomic + single-file visibility, workspace modes, validated downloads, and + root-confined destructive operations. +- Removed legacy party, manifest, artifact-discovery, remote-current, and lock + compatibility paths. +- Consolidated durable progress in the session manifest and removed the run + manifest domain model. +- Unified runner planning and execution decisions, separated invocation + lifecycle responsibilities, and avoided creating empty run workspaces for + fully reused or cleanup-only invocations. +- Added per-artifact analyze execution, checkpointing, reconciliation, and + recovery. +- Decomposed configuration validation by domain and made validation diagnostics + deterministic without treating incidental ordering or wording as a contract. +- Introduced immutable remote publish commits, one final current pointer, + explicit output planning, safe cross-run carried outputs, and independent + per-artifact remote locks. +- Added `cleanup` as the final canonical stage after `notify`, with validated + publish evidence, safe retry, explicit selection, and no separate cleanup + obligation. +- Replaced mutable command test hooks with invocation-scoped dependencies and + improved structural test diagnostics.