Skip to content

feat: durable message lifecycle from admission to execution - #3721

Open
Astro-Han wants to merge 18 commits into
apache:mainfrom
Astro-Han:fix/durable-message-lifecycle
Open

feat: durable message lifecycle from admission to execution#3721
Astro-Han wants to merge 18 commits into
apache:mainfrom
Astro-Han:fix/durable-message-lifecycle

Conversation

@Astro-Han

@Astro-Han Astro-Han commented Aug 24, 2026

Copy link
Copy Markdown
Contributor

Summary

This is the first end-to-end durable message lifecycle PR built from the latest main, replacing Draft PR #3633. It does not cherry-pick or continue the #3633 patch series.

The problem is simple: once turn.message.submit accepts a message, a Host crash must not make that message disappear, revive it into a queue, or execute it twice.

The solution keeps one durable authority for the message admission and one lifecycle/settlement owner. queued, leased, and in_flight are Host-memory projections rebuilt from durable facts.

The four durable values are facts, not a persisted provider state machine:

  • Accepted: SQLite admission and the canonical transcript row committed atomically.
  • HandedOff: a durable root admission/source proof, or an immutable steering event, proves that Root execution owns the message.
  • Executed: a durable provider-request proof exists downstream of that handoff proof. Steering uses its event timestamp as the lower bound.
  • Cancelled: a retract proof or terminal Stop proof closes the message without downstream execution.
flowchart LR
  S[turn.message.submit] -->|one SQLite admission + transcript transaction| A[Accepted]
  A -->|root admission/source proof| H[HandedOff]
  A -->|retract proof| C[Cancelled]
  H -->|provider request proof downstream of handoff| E[Executed]
  A -->|terminal Stop proof| C
  H -->|terminal Stop proof| C
Loading

First-principles ownership

  • SqliteSessionMetadataStore owns the durable message admission, transcript identity, ordering, edits, reorders, promotion, retract, lifecycle rows, and size boundaries.
  • RootAdmissionOwner owns the durable Root execution contract and source-message proof.
  • HostMessageCoordinator owns only the reconstructible queue projection and the shared proof classifier/settlement owner used by normal terminal cleanup and restart recovery.
  • Root admission is handed off before Runtime activation. Follow-up transcript rows are rebound to the successor turn before activation, so one submitted message keeps one canonical transcript identity.
  • Durable Session capability binding is derived from the durable Root execution contract; it does not depend on an in-memory provider marker.
  • RuntimeKernel no longer owns queue state, leasing, folding, retract, or fallback authority. The old method surface remains only as a no-state compatibility shell while CLI/Desktop projection work stays out of scope.

Crash-cut behavior

  1. Crash before SQLite admission: no accepted message exists, so there is nothing to recover.
  2. Crash after admission but before Root admission: recovery rebuilds an Accepted message into Host memory; it is not executed.
  3. Crash after Root admission but before activation: the durable Root contract is replayed; the root-source proof is handed off before activation.
  4. Crash after provider proof: recovery sees the downstream proof and settles Executed; it does not replay the message.
  5. Crash during terminal cleanup: recovery and normal terminal cleanup call the same settlement owner, so Accepted/HandedOff facts converge to Executed or Cancelled from durable proofs.

Scope

Included: atomic admission and transcript, edit/reorder/promotion/retract, successor handoff, proof-driven settlement, restart recovery, size boundaries, canonical transcript identity, durable capability derivation, and removal of the old RuntimeKernel queue authority.

Excluded: CLI/Desktop projection refactors and Side Conversation UI/hooks.

Verification

Only affected builds and tests were run; the full repository test suite was not run.

  • Exact pushed head: 2ea21a689.
  • npm --workspace @maka/runtime run build passed.
  • npm --workspace @maka/storage run build passed; SQLite metadata suite: 51 passed.
  • npm --workspace @maka/runtime-host run build passed; production SQLite + Runtime Host/UDS message, queue, and coordinator suites: 60 passed.
  • Root/recovery/canonical projection/Goal authority composition suite: 71 passed.
  • Runtime interaction regression suite: 11 passed.
  • npm run astryx:surface-inventory passed locally.
  • npm run format:check passed.
  • CI run 32758898698 passed for exact head 2ea21a689.
  • Fault coverage includes atomic transcript admission, oversized admission rejection before transcript mutation, edit/reorder/promotion/retract, ordered successor handoff, root admission without a Run, killed/graceful Host recovery, steering-event recovery, provider-proof settlement, and whole-session transcript de-duplication.

AI use

This PR was implemented with Codex assistance. The design, repository decisions, code changes, affected-test selection, review of Draft PR #3633 evidence, adversarial review, simplification audit, and final verification were directed and checked against the repository's durable authorities and production composition.

Preserve live Client capability bindings, make cancellation retries idempotent, and keep admission-backed transcripts out of compatibility Run synthesis until their root contract owns them.

Generated-by: Codex
@Astro-Han
Astro-Han marked this pull request as ready for review August 24, 2026 18:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant