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

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, 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. 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, 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 builds a revision-aware view used by the session rail UI.
• Runtime Host Cleanup – SessionManager.#stopSessionTree in 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

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.
• 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.
• 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 within the projectLinkedSessionTree function. Revision-specific wrappers are in packages/core/src/session-revisions.ts, sub-agent collection utilities are in packages/storage/src/session-bundle-policy.ts, and runtime consumers are in 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.

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