feat(runtime): complete production Write/Edit recovery
- Dominant language
- TypeScript
- Stars
- 5.4k
- Forks
- 502
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 715
Description
## Problem
Maka's Runtime resume documents distinguish the recovery work that has landed from the remaining Phase 3 work. Phase 3A established the durable T1/T2 boundary, `RecoveryResolver`, and atomic recovery-bundle persistence in #1521. Production Write/Edit recovery—trusted file evidence, a filesystem observer/reconciler, and the Host-owned recovery lifecycle—remains documented but is not represented by a focused GitHub issue.
Documentation alone is difficult to use as a progress tracker: contributors cannot query or assign the remaining work, connect child PRs to one canonical checklist, or quickly tell which parts have shipped. This also makes it easier for the design and implementation status to drift apart.
This issue tracks the narrow Phase 3 PR C/D work already described by the architecture. It does not introduce a new recovery design or promise generic automatic recovery for every tool.
Design sources:
- [Runtime resume architecture](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-architecture.md)
- [Runtime resume extraction ledger](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-extraction-ledger.zh-CN.md)
- [Phase 3–4 implementation roadmap](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-phase3-phase4-workspace-checkpoint-design.zh-CN.md)
Related roadmap: #544
## Desired outcome
Use this issue as the canonical, queryable progress tracker for production Write/Edit reconciliation. Keep the checklist and architecture status updated as child PRs land.
### Current documented baseline
- [x] Durable T1/T2 tool boundaries
- [x] Canonical tool-ledger scanner and `RecoveryResolver`
- [x] Atomic persistence and rebuild of recovery bundles
- [ ] Persist a versioned Write/Edit recovery contract and trusted file evidence before dispatch
- [ ] Add the Host-owned recovery contract registry
- [ ] Implement the filesystem worker and finalize-only Write/Edit observer/reconciler
- [ ] Scan eligible indeterminate operations and submit recovery bundles through the canonical SQLite authority
- [ ] Wire the Host lifecycle across startup, cancellation, shutdown, initialization failure, and owner conflicts
- [ ] Add production-shaped crash, concurrency, and lifecycle coverage
- [ ] Update the architecture status and this checklist as each slice lands
### Required first-version policy
- `matches_expected_state`: finalize without rewriting the file, synthesize the missing successful outcome, and commit a completed recovery bundle.
- `matches_prior_state`: park with `redo_disabled_pending_cas`.
- `diverged` or `unreadable`: park without mutating external state.
- Missing, incompatible, or unverifiable contracts and evidence must fail closed.
### Out of scope or explicitly deferred
- Automatic redo before a conditional replace/CAS protocol exists
- ShellRun reattachment, Bash replay, or generic child-process recovery
- Generic reconciliation for remote APIs or MCP tools
- Phase 4 Git workspace checkpoints, isolated restore, or durable rebaseline
- Exactly-once guarantees for arbitrary external side effects
## Alternatives or workarounds
Continue tracking the work only in architecture documents. That preserves the design, but it does not provide issue ownership, linked implementation progress, or a single status surface for contributors and maintainers.
Contributor guide
Research direction
Start with the Runtime resume architecture, extraction ledger, and Phase 3–4 implementation roadmap linked in the issue, then inspect the existing RecoveryResolver and canonical SQLite authority. Map the unchecked contract, observer/reconciler, scanning, and Host lifecycle items to implementation entry points. Done means the listed recovery behavior and production-shaped crash, concurrency, and lifecycle coverage are implemented, with the architecture status and checklist updated.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- sqlite, typescript
- Domain
- backend, databases, desktop
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100