narratio/docs/releases/v1.7.0.md

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 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 and Troubleshooting 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.