narratio/docs/roadmap/audit.md

Implementation Plan Summary

This is a concise, plain-language summary of implementation.md. It describes the intended real-world outcome of each stage without reproducing its implementation details.

1. Stage 1 — Collaborative workspace permissions: Treat ordinary Narratio and Notarius data as shareable and make managed workspaces group-writable, while retaining private handling for API keys.
2. Stage 2 — Safe identifiers: Reject campaign, session, run, artifact, and source identifiers that could escape their intended filesystem namespace, and use fuzz tests to cover platform-specific path tricks.
3. Stage 3 — Durable file replacement: Consolidate duplicated atomic-write functions into one shared mechanism that fully persists a replacement before reporting success.
4. Stage 4 — Confined writes and downloads: Rewrite destination mutations so symlinks or concurrent directory replacement cannot redirect writes, promotions, or downloads outside the intended root.
5. Stage 5 — Safe deletion and crash-recoverable locks: Confine recursive cleanup to its authorized root and replace stale lock-file existence checks with operating-system locks released automatically after process death.
6. Stage 6 — Protected API-key reads: Read API keys only from private, bounded, regular files without following symlinks or exposing key material in errors.
7. Stage 7 — Bounded external results: Prevent external adapters from causing memory or disk exhaustion by validating regular result files and enforcing generous, clearly reported per-adapter size limits.
8. Stage 8 — Complete subprocess termination: Ensure cancellation, timeout, or a safety-limit failure terminates and reaps an external command's entire process tree rather than only its parent process.
9. Stage 9 — Safe subprocess diagnostics: Redact known credentials from stdout/stderr, cap persisted diagnostics, and terminate runaway producers when those caps are reached.
10. Stage 10 — Safe publish inputs: Ensure publishing reads and uploads only verified regular files declared within the selected run, even during filesystem races.
11. Stage 11 — Consistent run identity: Resolve one campaign/session/run identity for an invocation, reject conflicting authorities, and prevent stale identity fields from leaking into a later run.
12. Stage 12 — Reliable failure recording: Consolidate terminal-failure persistence so handled errors reliably update authoritative session state and preserve any secondary persistence failures.
13. Stage 13 — Immutable remote-state model: Define a versioned immutable remote snapshot selected by a small pointer, while isolating old-format read compatibility so it can be removed after migration.
14. Stage 14 — Transactional publication: Upload and verify a complete immutable snapshot before one final pointer change makes it current, using an exact source-to-destination mapping instead of basename guesses.
15. Stage 15 — Safe remote locking and pagination: Use provider-enforced conditional writes so publishers cannot overwrite another owner's lock, and fail instead of looping when object-store pagination stops making progress.
16. Stage 16 — Retryable cleanup: Persist post-publication cleanup as a durable obligation so interrupted or failed deletion is retried and never mistaken for completed cleanup.
17. Stage 17 — Snapshot-consistent restore: Make restore and status use one selected immutable snapshot throughout the operation, and prevent --force from overwriting unsafe directory or non-file conflicts.
18. Stage 18 — Race-safe, portable restore: Serialize restore against runner reuse, leave durable evidence of incomplete restores, and replace unsafe producer-machine absolute paths with validated local references.
19. Stage 19 — Correct audio-cache reuse: Reuse downloaded audio only when its local bytes and recorded metadata match the selected remote object version.
20. Stage 20 — One previous-session resolver: Give restore, prepare, run, and dry-run one consistent view of required and optional previous-session inputs, while avoiding ambiguous matches and duplicate downloads.
21. Stage 21 — Strict configuration: Reject multiple YAML documents, invalid durations, implicit storage backends, and unmet previous-session expectations, while separating configuration tests by responsibility.
22. Stage 22 — Truthful product settings and temp-file ownership: Remove configuration fields that do nothing, reject unsupported notification settings, and guarantee cleanup of remote-configuration temporary files.
23. Stage 23 — Streaming WhisperX transport: Stream uploads instead of buffering entire audio files, reject unsupported endpoint schemes, and make retries, cancellation, fake-server recording, and race tests reliable.
24. Stage 24 — Correct prepare/transcribe transitions: Prevent stale previous data, cancelled or partial transcription work, and duplicate source identity from being recorded as successful current output.
25. Stage 25 — Authoritative output paths: Require adapters to honor the stage-requested output destination and consolidate duplicate singleton transcript resolution without confusing it with multi-source discovery.
26. Stage 26 — Shared extraction evidence: Consolidate duplicated extraction-bundle validation into one typed proof while allowing resume and catalog consumers to apply their distinct policies.
27. Stage 27 — Transcript-aware extraction reuse: Include the direct transcript's identity in extraction freshness checks so changed input cannot reuse stale structured artifacts.
28. Stage 28 — One effective artifact selection: Resolve configured and explicitly selected artifacts once, then use that same typed set for prerequisites, extraction catalogs, analyze inputs, and execution planning.
29. Stage 29 — Predictable analyze planning: Represent optional and required analyze inputs explicitly, produce deterministic dependency errors, and give operators correct remediation commands.
30. Stage 30 — Contract cleanup: Remove dead or misleading interfaces and helpers, move static Audita configuration to its proper owner, and correct stale contract comments.
31. Stage 31 — Enforced automated validation: Require tests, race checks, vet, builds, and example validation for changes and releases, while consolidating redundant broad tests without losing focused coverage.
32. Stage 32 — Documentation and closure: Reconcile normative documentation with the completed behavior and verify that every planned remediation has one completed, traceable implementation stage.

Every stage's purpose was readily determinable from the implementation plan; no stage required an uncertainty note.