How Session Branching, Archiving, Search, and Recovery Work in Apache Maka

TLDR: Apache Maka implements session branching via immutable snapshots of the ExecutionBoundary, soft-delete archiving with ledger-indexed metadata, scoped search through the task ledger, and two-phase recovery that replays events from durable logs.

Apache Maka's runtime architecture treats conversations as durable, branching sessions that persist beyond process lifetimes. The system combines immutable session boundaries, soft-delete archiving, and ledger-based indexing to enable complex conversational workflows that survive crashes and support parallel exploration. This design centers on the SessionManager (packages/runtime/src/session-manager.ts), which orchestrates the entire lifecycle from branch creation to disaster recovery.

Session Branching: Isolating Alternative Execution Paths

When a user explores a tangent or alternative approach, Maka creates an isolated copy of the conversation state without mutating the original session. This mechanism relies on deterministic snapshots and explicit parent-child relationships tracked in the ledger.

Snapshots at the ExecutionBoundary

In packages/runtime/src/sandbox/execution-boundary.ts, the ExecutionBoundary defines the security and state perimeter of a session. At each turn boundary, the system captures a deterministic snapshot of this boundary. When branching occurs, the current boundary state is cloned into a new session instance, ensuring the original remains immutable and suitable for deterministic replay.

The branchFromTurn API

The SessionManager.branchFromTurn() method in packages/runtime/src/session-manager.ts instantiates a new session with a unique sessionId, a parentSessionId referencing the source, and a branchOfTurnId marking the exact divergence point. The UI layer (packages/ui/src/session-workbar.tsx) renders this relationship in branch banners, displaying the lineage as 分自 <parentSessionName>. This guarantees that the original session's ledger stays append-only while the branch receives an independent execution context.

// Create a new branch from a specific turn to explore an alternative
const branch = await SessionManager.branchFromTurn(originalSessionId, {
  sourceTurnId: turnId,
  name: "Exploring alternative approach"
});
// Returns: { sessionId, parentSessionId, branchOfTurnId, ... }

Archiving: Soft-Delete for Storage Efficiency

Archiving allows the system to hide obsolete artifacts from active queries while preserving data for compliance, audit, and later recovery. This is implemented as a soft-delete pattern rather than destructive removal.

The Archive Metadata Contract

According to docs/work-board-contract.md, active items carry no archivedAt timestamp, while archived items receive a Unix millisecond timestamp. This metadata distinction allows the storage layer to keep data on disk but filter it from standard result sets. The RuntimeHost exposes the archival interface, marking artifacts without breaking the append-only nature of the session ledger.

Filtering Archived Content

When querying the session state, the runtime respects the include_archived (or includeArchived) boolean parameter. By default, all queries exclude archived items, improving performance and reducing noise. When historical data is required, explicit opt-in retrieves both active and archived records.

// Archive a specific tool result after completion
await RuntimeHost.archiveToolResult({
  sessionId,
  artifactId,
  archivedAt: Date.now()
});

// Query excluding archived items (default behavior)
const activeOnly = await Ledger.search({
  sessionId,
  query: "design requirements",
  includeArchived: false
});

Search: Indexed Artifact Retrieval

Each session maintains an append-only task ledger that indexes all tool-generated artifacts, enabling fast retrieval without re-executing expensive external calls.

The Task Ledger Index

The docs/session-task-ledger-lifecycle.md defines the ledger as the source of truth for task execution, outputs, and archival state. Search providers (such as web-search implementations) attach to the current session model and reuse the same credentials, allowing per-session tool surfaces as described in the web-search provider capability documentation.

Session-Scoped Search

When searching, the system queries the session-specific ledger rather than external APIs. This allows retrieval of previously archived results instantly. The ledger's indexing supports both active and archived artifact lookup via the includeArchived flag, ensuring comprehensive historical analysis when needed.

// Search within the current session's ledger
const results = await Ledger.search({
  sessionId: currentSessionId,
  query: "API schema definition",
  includeArchived: true  // Retrieve archived artifacts alongside active ones
});

Recovery: Rehydrating State After Interruptions

After process restarts or host failures, the SessionManager rebuilds the exact in-memory state from durable logs, ensuring conversational continuity without data loss.

Phase 3: Boundary Re-establishment

As documented in docs/architecture/runtime-resume-phase3-phase4-workspace-checkpoint-design.zh-CN.md, recovery Phase 3 re-establishes the session's ExecutionBoundary and authority context. This phase validates that the resumed session maintains its original security constraints and credential scopes before accepting new input.

Phase 4: Event Replay and Ledger Validation

Phase 4 replays recorded events from the task ledger, skipping archived artifacts unless specifically required for state reconstruction. The docs/architecture/runtime-resume-extraction-ledger.zh-CN.md describes branch/revision pre-flight checks that reject any continuation violating the original authority guarantees. This ensures that a resumed session resumes exactly where it left off, even if some turns were only partially persisted before the crash.

// Recover a session after crash or process restart
const recoveredSession = await SessionManager.recoverSession(sessionId);
// Rehydrates ExecutionBoundary, replays events from ledger, 
// and restores archived artifacts on demand

Summary

• Branching creates isolated execution contexts via SessionManager.branchFromTurn, cloning the ExecutionBoundary snapshot while preserving the immutable parent session.
• Archiving uses soft-delete semantics (archivedAt timestamp) defined in the work-board contract, hiding data from default queries while retaining it for recovery.
• Search operates on the session-scoped task ledger (docs/session-task-ledger-lifecycle.md), allowing fast retrieval of both active and archived artifacts via the includeArchived parameter.
• Recovery proceeds in two phases—boundary re-establishment (Phase 3) and event replay (Phase 4)—validating authority constraints before resuming the session.

Frequently Asked Questions

What is the difference between deleting and archiving a session artifact in Apache Maka?

Archiving performs a soft delete by setting an archivedAt timestamp on the artifact metadata. The data remains on disk and can be retrieved with includeArchived: true, but it is excluded from standard search results. Hard deletion is not supported in the core session lifecycle, ensuring auditability and recovery capabilities.

How does Apache Maka ensure the original session remains unchanged when branching?

The branchFromTurn method in packages/runtime/src/session-manager.ts creates a new session with its own sessionId and parentSessionId while snapshotting the ExecutionBoundary at the turn boundary. The original session's ledger remains append-only and immutable; the branch writes to an independent ledger, preventing any side effects on the parent conversation.

Can archived artifacts be included in search results?

Yes. The Ledger.search method accepts an includeArchived boolean parameter. When set to true, the query returns both active and archived artifacts. When false (the default), only active items appear in results, optimizing query performance for current workflow needs.

What happens if a recovery attempt violates the original session's authority constraints?

During Phase 3 of recovery, the system runs branch/revision pre-flight checks against the ExecutionBoundary as documented in docs/architecture/runtime-resume-extraction-ledger.zh-CN.md. If the resumed context cannot satisfy the original authority requirements—for example, if credentials have expired or security policies changed—the recovery rejects the continuation to maintain the session's security invariants.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}