Make atomic file replacement crash durable

docs/internal/fileops.md

@@ -0,0 +1,35 @@
+# Internal: File Operations
+
+`internal/fileops` owns the narrow mechanics for durable replacement of one
+byte file. Callers keep ownership of serialization, validation, cancellation,
+and destination-directory policy.
+
+## Replacement Contract
+
+`ReplaceFileAtomic` requires an existing destination directory. It creates a
+sibling temporary file, writes the complete byte sequence, applies the
+caller-supplied mode, syncs and closes the file, runs an optional pre-rename
+check, replaces the destination with a rename, then syncs the containing
+directory.
+
+The pre-rename check is the last point at which a caller can cancel without
+installing a new destination. A failure before the rename leaves the old
+destination unchanged and removes the temporary file; any cleanup failure is
+returned alongside the primary failure. A failure after the rename may leave
+the new file visible, but it is not reported as crash-durable.
+
+Replacement follows the operating system's same-filesystem rename semantics.
+If a platform cannot replace an existing destination, the operation returns an
+error and never removes the old file as an emulation step.
+
+## Directory-Sync Support
+
+Linux and macOS attempt to sync the destination directory. Windows opens the
+directory with backup semantics and flushes its buffers. If either operation
+is unavailable for the platform, directory handle, or filesystem,
+`ErrDirectorySyncUnsupported` is returned. Narratio does not treat that result
+as successful crash-durable replacement.
+
+`WriteFileAtomic`, copy helpers, and downloaded temporary-file installation
+retain their compatibility behavior of creating the destination parent with
+the repository's workspace permissions before using this contract.

docs/internal/manifest.md

@@ -48,9 +48,15 @@ The model admits these stage states:
 
 - validates loaded documents;
 - normalizes missing maps/stage records;
-- writes atomically via temp file + rename;
+- writes through a sibling temporary file, syncing the completed file and
+  destination directory after atomic replacement;
 - updates `updated_at` on save.
 
+If the operating system or filesystem cannot sync a directory, save returns an
+explicit error instead of claiming crash-durable replacement. A returned error
+after the rename can therefore leave the new manifest visible but not confirmed
+durable; callers must reload it before retrying.
+
 ## Execution Semantics
 
 The application runner marks an executing stage running and then succeeded or

docs/internal/overview.md

@@ -35,7 +35,7 @@ progress and artifact services resolve durable inputs and outputs.
 | Artifacts and paths | `internal/artifacts`, `internal/pathsafe` | Artifact identities and resolution, local and remote path/key models, current-state discovery, and confined relative destinations. |
 | Previous-session cache | `internal/previouscache` | Deterministic planning and materialization requirements for configured previous-session inputs. |
 | Artifact policy | `internal/artifactpolicy` | Source and destination policy, configured artifact identity validation, and publish destination safety. |
-| Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, `internal/fileops` | Transcript and artifact data contracts plus narrow atomic filesystem helpers. |
+| Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, [`internal/fileops`](fileops.md) | Transcript and artifact data contracts plus durable single-file replacement helpers; unsupported directory syncing is reported explicitly. |
 | Logging | `internal/logging` | Application logger construction and shared structured logging behavior. |
 
 The application boundary composes concrete implementations. Stages depend on

docs/roadmap/implementation.md

@@ -18,7 +18,7 @@ All stages are pending when this plan is created.
 | ---: | --- | --- | --- |
 | 1 | Align data classification and group workspace modes | RSK-004 | Completed |
 | 2 | Enforce safe identifiers and fuzz path/source contracts | COR-002, TST-013 | Completed |
-| 3 | Consolidate crash-durable atomic file replacement | RSK-002, DUP-001, DUP-005 | Pending |
+| 3 | Consolidate crash-durable atomic file replacement | RSK-002, DUP-001, DUP-005 | Completed |
 | 4 | Add confined destination and download/install capabilities | COR-003, DUP-003, TST-003 | Pending |
 | 5 | Confine recursive cleanup and replace sentinel locks | RSK-003 | Pending |
 | 6 | Harden API-key file acquisition | RSK-010 | Pending |