apache / apache/maka

feat(runtime): complete production Write/Edit recovery

Open
#4,319 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.