# Implementation Plan Summary

This is a concise, plain-language summary of
[`implementation.md`](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.