AstrBot-Desktop/docs/spikes/P00-05-nas-file-transaction.md

71 行
3.3 KiB
Markdown

# P00-05: NAS File Transaction
- Status: Local transaction and recovery passed; real UNC execution blocked by missing authorized fixture
- Date recorded: 2026-07-18
- MVP gate: Required before any NAS write feature
## Objective
Verify a recoverable UNC transaction using plan, dry run, temporary copy, size and SHA-256 verification, atomic destination commit, conflict handling, and interruption recovery while preserving the source.
## Environment
- Host: Windows 11 x64
- Authorized UNC fixture: not supplied
- Rust toolchain: rustc/cargo 1.97.1
- MSVC C++ build tools: verified by native builds
- Real user or production files: prohibited
## Minimal validation implementation
The Spike is expected to operate only on a user-authorized disposable source fixture and destination share. It must:
- Tokenize the selected source path.
- Reject paths outside the authorized source and destination roots.
- Produce a non-mutating dry-run plan.
- Copy to a unique temporary destination.
- Verify byte count and SHA-256.
- Commit by renaming within the destination filesystem.
- Apply ask, rename, or skip conflict policy without overwrite.
- Persist resumable transaction state without credentials.
- Preserve the source in every P00 outcome.
## Required execution
1. Obtain explicit user authorization for disposable source and UNC destination fixtures.
2. Generate unique test data inside the fixture.
3. Execute and inspect a dry run.
4. Copy to a temporary destination and verify size and SHA-256.
5. Commit to the final name and confirm the source still exists.
6. Exercise ask, rename, and skip conflicts.
7. Interrupt during copy and verify no final destination is exposed.
8. Resume or restart safely and verify source preservation.
9. Inject hash mismatch and confirm no commit or cleanup occurs.
## Actual execution result
The transaction implementation and disposable local-fixture tests passed. They cover non-mutating plan/dry-run, copy to a unique temporary name, byte-count and SHA-256 verification, atomic final rename, ask/rename/skip conflict behavior without overwrite, injected interruption and hash mismatch, restart-safe state, and source preservation.
No real UNC path was read or written. The user did not identify an authorized disposable source directory and destination share, so executing the same flow against a NAS would violate the project safety rule.
This is an environment/authorization block for the UNC transport check, not a claim that SMB interruption behavior passed.
## Log summary
Command: `cargo test --workspace` on generated temporary directories. Result: passed. No source fixture was deleted, no existing destination was overwritten, and no NAS credential was used or logged.
## Known limitations
- Atomic rename guarantees depend on the destination filesystem and share behavior.
- Network interruption and SMB caching can affect observability.
- P00 does not validate recycle-bin or source-cleanup behavior.
- Performance on large files remains unmeasured.
## Security impact
Silent overwrite or premature source cleanup can cause data loss. Credentials must remain in Windows secure storage, and remote payloads must never provide unrestricted local or UNC paths.
## Recommendation
Do not enable NAS writes until this Spike has executed against a disposable authorized share. P00 must preserve sources and treat source cleanup only as a non-executed plan field.