refactor(runtime): make Session commit manifest the sole continuation authority

[FradSer]

Area

Runtime / API / Database

Problem

Mosoo's durable Session continuation state is currently represented by several related but independently persisted authorities: Run terminal state, Session workspace backup records, native Harness resume references, frozen execution snapshots, resource/attachment manifests, recorded artifacts, platform events/history, and (for write-capable tools) external-effect state.

Each record has a valid local purpose, but a recovery path needs one answer to a stronger question: which exact successful Session state is safe to restore and continue from? Without one durable commit boundary that names every continuation-relevant version, the admission, restore, audit, and recovery code must infer consistency across multiple rows and asynchronous operations. That increases the risk of mixing a newer native resume reference with an older workspace, treating artifacts as a workspace substitute, or replaying work while an external effect remains indeterminate.

This is particularly important as Mosoo pivots toward API-first durable Sessions in #546 / #582. A public Session needs one auditable, internally atomic continuation authority rather than product-specific runtime heuristics.

Related work:

• fix(runtime): persist uncertainty for external tool effects #412 records the unresolved durable state for external write effects.
• perf(runtime): bound Cattle artifact restore latency and memory #563 optimizes artifact rehydration, which must not become a second workspace truth source.
• refactor(runtime)!: enforce durable protocol v3 boundaries #586 owns protocol-v3 durability and the remaining atomic credential-exclusion backup prerequisite.
• feat(platform): pivot Mosoo to an API-first managed Agent runtime #546 and feat(api): add the durable Agent Session API #582 define the API-first durable Session direction.

Proposal

Introduce a runtime-owned, append-only SessionCommit (name illustrative) as the sole continuation authority for a Session. It does not create a new generic memory store or duplicate the data it references. It atomically records the versions/identities of the existing durable state that together make one successfully committed Session boundary:

SessionCommit
- sessionId
- successfulRunId
- workspaceBackupId
- nativeResumeRefVersion
- resourceManifestVersion
- artifactManifestVersion
- effectLedgerWatermark
- executionSnapshotVersion
- committedAt
- restoreStatus

The exact field names, optionality, and storage layout should follow the existing schema and runtime contracts. In particular, a runtime without a native resume capability must explicitly represent its absence instead of synthesizing one.

Required invariants

1. A follow-up Run is admitted only after the latest applicable SessionCommit is ready.
2. Restore resolves one explicit ready commit and restores only state referenced by that commit.
3. A failed, cancelled, or uncommitted Run never creates or overwrites a ready commit; the preceding ready commit remains authoritative.
4. A commit remains recoverable under the existing Session retention/deletion policy. Permanent Session deletion removes its commit records and referenced recoverable state according to the existing lifecycle rules.
5. If an external effect at or before the candidate watermark is unknown, the commit must not authorize automatic replay. Recovery must reconcile it or require explicit resolution as defined by fix(runtime): persist uncertainty for external tool effects #412.
6. Artifacts remain explicit Session outputs and an artifact manifest is only one commit dimension; it must not silently substitute for the committed workspace backup.
7. Short-lived credentials and current-message attachment mounts remain excluded from the durable boundary. This issue must not weaken refactor(runtime)!: enforce durable protocol v3 boundaries #586's release constraint requiring an atomic exclusion guarantee.
8. Every restore, commit, reconciliation block, and failed validation is auditable against the specific commit ID.

Scope

• Define the commit state machine and its relation to Run terminalization, workspace backup readiness, native resume persistence, effects, and restore.
• Make the ready transition the runtime's single next-turn admission boundary.
• Migrate existing continuation logic to resolve state through the commit rather than independently selecting latest rows.
• Add focused fault-injection coverage for partial commit stages, Driver loss, backup failure, stale native resume references, unknown effects, retry/idempotency, cold restore, and Session deletion.
• Update architecture and public/session semantics to describe the one durable continuation boundary accurately.

Non-goals

• Vector retrieval, semantic memory, automatic summarization, or an Agent-level personal-memory product.
• Replacing R2/Sandbox backup storage, native Harness resume, artifact records, resource records, or event history with duplicated payloads in a new table.
• Relaxing Session isolation or enabling cross-Session restore.
• Implementing automatic external-effect reconciliation before fix(runtime): persist uncertainty for external tool effects #412 defines provider/tool capabilities and resolution rules.
• Circumventing the writer-freeze / forbidden-path backup safety requirement tracked by refactor(runtime)!: enforce durable protocol v3 boundaries #586.

Alternatives considered

1. Keep separate records and enforce ordering in each caller. This retains the current ambiguity and duplicates consistency logic across admission, restore, reclaim, and audit paths.
2. Use artifacts as the universal continuation source. Artifacts are intentionally explicit outputs; they omit arbitrary workspace state, Git state, dependency/tool-local state, and native resume context.
3. Create a new monolithic memory blob. This duplicates existing durable storage and would blur ownership, retention, file semantics, and secret-exclusion boundaries.
4. Only add a checkpoint ready boolean to Session. A boolean cannot identify the exact workspace/native/resource/effect versions that were committed together or support audit and retry fencing.

Compatibility and migration

This is an internal durability refactor; the public Session ID remains the sole required lifecycle handle. Existing Sessions predating the commit model need an explicit migration/recovery policy: either a bounded grandfathered compatibility path that cannot claim stronger restore semantics, or a one-time commit creation only after the next successful turn. Do not silently treat independently latest rows as though they were atomically committed.

The schema/data migration must be additive and backfill-safe. No existing backup, artifact, or event retention may be shortened. Rollout must be gated on the credential-exclusion safety precondition in #586.

Acceptance criteria

• Architecture documents one Session-level continuation commit as the authoritative ready boundary.
• The data model identifies every continuation-relevant state version without duplicating its payload.
• A new input cannot be admitted while its prior turn lacks a ready commit.
• Cold and warm continuation resolve the same committed boundary.
• Fault-injection tests prove failed/cancelled runs and partial persistence cannot advance the ready boundary.
• Unknown external effects block automatic replay according to fix(runtime): persist uncertainty for external tool effects #412.
• Tests prove credentials and unselected current-message attachments are absent from recoverable state, subject to refactor(runtime)!: enforce durable protocol v3 boundaries #586's upstream safety gate.
• Cross-Session/tenant restoration remains impossible.
• Existing retention and permanent-deletion behavior is preserved and covered.

Contribution

I can provide product feedback.