105 lines
6.9 KiB
Markdown
105 lines
6.9 KiB
Markdown
# 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.
|