# How Apache Maka Projects Linked Session Trees: A Technical Deep Dive

> Learn how Apache Maka projects linked session trees by transforming flat logs into hierarchical views. Explore the `projectLinkedSessionTree` function and its handling of complex session data.

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

---

**Maka projects linked session trees by transforming a flat SQLite log into a read-only hierarchical view using the `projectLinkedSessionTree` function in [`packages/core/src/session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts), which organizes `SessionSummary` objects into roots and children maps while handling cycles, missing parents, and logical ID aliasing.**

Apache Maka stores every runtime interaction as a flat list of **Session** rows in its SQLite log. To present a hierarchical view that respects sub-agent ownership and revision boundaries, the core library constructs **linked session trees**—a projection that nests child sessions beneath their logical parents while keeping the flat list as the single source of truth.

## The Core Projection Algorithm in `projectLinkedSessionTree`

The projection is performed by **`projectLinkedSessionTree`**, defined in [`packages/core/src/session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts). This function walks a list of `SessionSummary` objects and produces two immutable structures:

- **`roots: SessionSummary[]`** – Sessions that have no durable parent, or whose parent is missing or cyclic. These appear as top-level nodes.
- **`childrenByParentId: ReadonlyMap<string, readonly SessionSummary[]>`** – A map from a parent session's visible identifier to its direct children.

### Step 1: Durable Parent Lookup and Logical Aliasing

Each session may carry a **`parentSessionId`** representing the physical parent persisted by the storage layer. However, callers can supply **`parentSessionIdAliases`** via `LinkedSessionTreeProjectionOptions`. This map rewrites durable IDs to the **logical** IDs that a revision or UI wants to display—for example, when a parent revision is superseded but its child should remain attached to the new logical parent.

### Step 2: Cycle Detection and Missing Parent Handling

If a parent cannot be found in the session list, or if the algorithm detects a cycle in the parent-child chain, the session is **promoted to a root**. This guarantee ensures that no child session disappears from the UI, maintaining robustness against data corruption or incomplete logs.

### Step 3: Sub-Agent Session Integration

Sessions created by a sub-agent carry a **`SubagentSessionParent`** record. The helper **`collectSubagentSessionTree`**, implemented in [`packages/storage/src/session-bundle-policy.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/session-bundle-policy.ts), extracts the logical parent chain for these children and feeds them into the same projection routine. This allows sub-agent sessions to appear correctly nested within their parent agent's tree regardless of physical storage boundaries.

## Consuming Linked Session Trees in Maka

Once projected, the `LinkedSessionTree` is consumed by multiple subsystems:

- **Desktop / TUI Navigation** – `projectRevisionLinkedSessionTree` in [`packages/core/src/session-revisions.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session-revisions.ts) builds a revision-aware view used by the session rail UI.
- **Runtime Host Cleanup** – `SessionManager.#stopSessionTree` in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) traverses the tree to cleanly stop or clean up entire session branches.

By separating the **flat** storage model from the **projected** hierarchical model, Maka guarantees **append-only integrity** (the log never changes; the tree is a pure, read-only view), **robustness** (every session remains reachable through root promotion), and **flexibility** (alias maps allow revision-level reshaping without touching underlying data).

## Practical Implementation: Code Examples

```typescript
import { SessionSummary } from '@maka/core';
import { projectLinkedSessionTree } from '@maka/core/session';
import { projectRevisionLinkedSessionTree } from '@maka/core/session-revisions';

// 1️⃣ Build a basic linked tree from raw sessions
const rawSessions: SessionSummary[] = await loadSessionsFromSQLite();
const tree = projectLinkedSessionTree(rawSessions);
console.log(tree.roots.length, 'top‑level sessions');
console.log(tree.childrenByParentId.get('parent‑id')?.length ?? 0, 'children');

// 2️⃣ Use a logical alias map (e.g. when a revision replaces its parent)
const aliasMap = new Map<string, string>([
  ['old‑revision‑id', 'new‑revision‑id'],
]);
const treeWithAlias = projectLinkedSessionTree(rawSessions, {
  parentSessionIdAliases: aliasMap,
});

// 3️⃣ Build a revision‑aware tree for the UI
const revisionTree = projectRevisionLinkedSessionTree(rawSessions, {
  parentSessionIdAliases: aliasMap,
});

```

## Summary

- **Linked session trees** in Apache Maka are read-only projections created by `projectLinkedSessionTree` in [`packages/core/src/session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts).
- The algorithm produces `roots` and `childrenByParentId` structures that handle durable parent IDs, logical aliases, cycles, and missing parents.
- **Sub-agent sessions** integrate via `collectSubagentSessionTree` in [`packages/storage/src/session-bundle-policy.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/session-bundle-policy.ts).
- The projection decouples immutable flat storage from hierarchical UI views, ensuring **append-only integrity** and **fault tolerance**.

## Frequently Asked Questions

### What is the difference between a durable parent ID and a logical parent ID in Maka?

A **durable parent ID** is the physical `parentSessionId` persisted in the SQLite log, representing the actual storage-layer relationship. A **logical parent ID** is a display-time abstraction provided via `parentSessionIdAliases` in `LinkedSessionTreeProjectionOptions`, allowing the UI to rewrite parent references—for example, attaching children to a superseded revision's replacement without modifying the stored data.

### How does Maka handle cyclic parent references in session trees?

When `projectLinkedSessionTree` detects a cycle or cannot locate a referenced parent in the session list, it **promotes the child to a root**. This ensures that every session remains visible in the UI rather than being orphaned or causing infinite recursion during tree traversal.

### Where does the session projection logic reside in the Apache Maka codebase?

The primary projection logic lives in [`packages/core/src/session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts) within the `projectLinkedSessionTree` function. Revision-specific wrappers are in [`packages/core/src/session-revisions.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session-revisions.ts), sub-agent collection utilities are in [`packages/storage/src/session-bundle-policy.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/session-bundle-policy.ts), and runtime consumers are in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts).

### Why does Maka separate flat storage from projected session trees?

This separation enables **append-only integrity** on the storage layer while allowing flexible, read-only hierarchical views for different contexts (UI navigation, runtime cleanup, revision management). The flat log remains the single source of truth, while projections can apply logical aliases and handle edge cases like cycles without risking data mutation.