langgenius / langgenius/mosoo

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

Open
#589 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
147
Forks
26
Avg merge
5h 6m
Merged PRs (30d)
40

Description

## 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:

- #412 records the unresolved durable state for external write effects.
- #563 optimizes artifact rehydration, which must not become a second workspace truth source.
- #586 owns protocol-v3 durability and the remaining atomic credential-exclusion backup prerequisite.
- #546 and #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:

```text
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 #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 #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 #412 defines provider/tool capabilities and resolution rules.
- Circumventing the writer-freeze / forbidden-path backup safety requirement tracked by #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 #412.
- [ ] Tests prove credentials and unselected current-message attachments are absent from recoverable state, subject to #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.

Contributor guide

Open the contributing guide

Research direction

Start by reading the existing runtime contracts for Run terminalization, workspace backups, native resume state, effects, restore, admission, and Session deletion, then review #412, #546, #582, and #586. Define the SessionCommit state machine and migration policy before implementation. Done means the ready commit is the sole admission and restore boundary, with the listed fault-injection, retention, isolation, credential-exclusion, and unknown-effect tests passing.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, backend, database
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.