63 lines
4.0 KiB
Markdown
63 lines
4.0 KiB
Markdown
# Operation State Implementation Plan
|
|
|
|
> **For agentic workers:** Use superpowers:executing-plans with test-driven-development. No production access or automatic commits.
|
|
|
|
**Goal:** Persist operation identity and status under an exclusive OS lock, refusing duplicate execution and ambiguous state.
|
|
|
|
**Architecture:** An internal state package acquires a nonblocking per-directory host lock and returns a session. Every mutation saves a complete bounded snapshot using write/sync/rename; the session becomes unusable on persistence errors. The directory must be a pre-existing trusted local directory, not a network share.
|
|
|
|
**Tech Stack:** Go standard library, Linux flock / Windows LockFileEx, os.Root.
|
|
|
|
**Spec:** docs/2026-09-25-complete-optimization-proposal.md sections 7, 8, 12, 14.
|
|
|
|
## Constraints
|
|
|
|
- Current directory and codex/new-deployment-architecture branch; preserve prior edits.
|
|
- No CLI write endpoint or Docker/application operation is enabled by this package.
|
|
- No automatic deletion of lock files, stale-task replay or corrupted-state reset.
|
|
- Lock-file inode must remain stable; close releases the OS lock.
|
|
- Metadata integrity is not authorization, and terminal success must be verified by the future executor.
|
|
- Linux is the production target; Windows provides development tests. Power-loss durability on Windows is not claimed.
|
|
|
|
## Task 1: Exclusive host sessions
|
|
|
|
Files: internal/state/store.go, lock_linux.go, lock_windows.go, lock_unsupported.go, store_test.go.
|
|
|
|
Interface: `Acquire(directory, hostID string) (*Session, error)`; `Session.Close() error`.
|
|
|
|
- [x] Write tests: second session returns ErrBusy, closed session rejects use, independent directories do not block each other, invalid IDs fail, killed child releases OS lock.
|
|
- [x] Run `go test ./internal/state`; observe missing implementation failure.
|
|
- [x] Implement nonblocking OS lock with private regular file inside os.Root; refuse unsupported systems and symlink state files.
|
|
- [x] Run tests using real temp directories and subprocesses, not mocked locks.
|
|
|
|
```go
|
|
second, err := Acquire(dir, "host-one")
|
|
if second != nil || !errors.Is(err, ErrBusy) { t.Fatal("host lock bypassed") }
|
|
```
|
|
|
|
## Task 2: Persistent idempotency and state transitions
|
|
|
|
Files: internal/state/operation.go, snapshot.go, operation_test.go.
|
|
|
|
Interfaces: `Begin(id, planHash string) (Operation, bool, error)`; `Get(id string) (Operation, error)`; `Advance(id string, revision uint64, next Status) (Operation, error)`.
|
|
|
|
- [x] Tests: duplicate ID/hash returns original with created=false; same ID/different hash conflicts; reopened state persists; unrelated new operation blocked by unresolved prior operation; stale revision and running-to-running rejected; terminal results immutable.
|
|
- [x] Tests: corrupt/truncated/oversized/host-mismatched snapshots rejected; write failure poisons session and never returns success; surviving running state is not silently reset.
|
|
- [x] Implement canonical checksummed snapshot, bounded read, unique temporary file, file sync, atomic rename and Linux directory sync. Any persistence failure requires closing/reopening and checking the actual state.
|
|
- [x] Run full tests and real killed-child recovery test. Abrupt process death is not a power-loss durability test.
|
|
|
|
```go
|
|
again, created, err := session.Begin("op-one", hash)
|
|
if err != nil || created || again.Revision != 1 { t.Fatal("duplicate submission changed state") }
|
|
```
|
|
|
|
## Task 3: Verification and documentation
|
|
|
|
- [x] Run gofmt, `go test ./... -count=1`, `go vet ./...`, native CLI smoke tests and Linux cross-build including state tests.
|
|
- [x] Independent read-only code review; repair actionable findings with regression tests.
|
|
- [x] Update docs/implementation-status.md and internal/state/README.md with lifecycle, trusted-root requirements, residual risks, and remaining systemd/executor work.
|
|
|
|
Additional evidence: Ubuntu WSL full suite and `go test -race ./internal/state` passed.
|
|
Windows symlink tests skipped for unavailable privilege; both passed on Linux.
|
|
Regression tests cover missing initialized snapshots and 113,357-record capacity boundary.
|