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

> Discover how Apache Maka handles session branching, archiving, search, and recovery. Learn about immutable snapshots, soft-delete archiving, ledger-indexed metadata, and two-phase recovery for robust data management.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-08-27

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.

```typescript
// 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`](https://github.com/apache/maka/blob/main/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.

```typescript
// 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`](https://github.com/apache/maka/blob/main/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.

```typescript
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.

```typescript
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.