# How Session Identity is Defined in Apache Maka: Architecture and Implementation

> Learn how Apache Maka defines session identity with a human-readable name and an immutable session ID for routing, management, and stream continuity in its peer-mesh runtime.

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

---

**Session identity in Apache Maka comprises two distinct elements—a human-readable session name for UI recognition and an immutable opaque session ID that uniquely routes messages, manages branching, and ensures stream continuity across the peer-mesh runtime.**

In the `apache/maka` repository, session identity serves as the foundational mechanism for tracking logical conversation threads through the UI layer and distributed runtime. The architecture cleanly separates user-facing identification from internal routing primitives, ensuring that every message submission, revision history, and network stream remains unequivocally attached to the correct logical session.

## Core Components of Session Identity

Maka defines session identity through a dual-concept model that balances usability with technical precision.

### Human-Readable session Names

The **session name** provides the user-facing label that appears in browser title bars and conversation headers. In [`packages/ui/src/titlebar-session-identity.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/titlebar-session-identity.tsx) at line 41, the `TitlebarSessionIdentity` component accepts a `sessionName` prop that renders the active conversation title (e.g., "Chat with Assistant"). This component handles display logic and rename callbacks but intentionally shields users from the underlying technical identifier.

### The Opaque session ID

The **session ID** is an immutable string that functions as the canonical reference throughout the system. Unlike the display name, this identifier appears in runtime APIs such as `window.maka.sessions.submitMessage` and internal components including `TranscriptViewportNavigation` and `ResumablePeerStream`. The architectural specification in [`docs/architecture/peer-mesh-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/peer-mesh-architecture.md) (line 170) establishes this ID as the "logical stream session identity" that persists across network reconnects and process restarts.

## How session ID is Used Throughout the System

The session ID threads through four critical subsystems, enabling consistent state management across distributed contexts.

### Title Bar Navigation

`TitlebarSessionIdentity` manages navigation to parent sessions through callback props that internally carry the session ID. While the component displays only the human-readable name, navigation actions—such as clicking a breadcrumb to return to a root conversation—invoke handlers with the specific session ID required for the transition.

### Branch Navigation and Context

The `SessionContextLayer` component in [`packages/ui/src/session-context-layer.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/session-context-layer.tsx) exposes branching capabilities through the `SessionContextBranch` interface defined at lines 41-44:

```typescript
export interface SessionContextBranch {
  parentSessionId: string;      // ← the logical session identifier
  parentSessionName: string;
  fromAbortedTurn?: boolean;
}

```

When users interact with branch breadcrumbs, the `onBranchNavigate(sessionId)` callback receives the `parentSessionId`—the opaque identifier that ensures navigation targets the correct conversation fork, even when multiple sessions share identical display names.

### Revision Tracking

Session identity enablestime-travel functionality through revision management. The `SessionContextRevision` interface (lines 47-52 of [`session-context-layer.tsx`](https://github.com/apache/maka/blob/main/session-context-layer.tsx)) tracks historical states:

```typescript
export interface SessionContextRevision {
  current: number;
  total: number;
  previousSessionId?: string;   // ← ID of the prior revision
  nextSessionId?: string;       // ← ID of the next revision
}

```

These ID references allow the UI to request specific historical states from the backend, ensuring that rollbacks and forward navigation operate on the correct conversation snapshots.

### Network Resumption and Peer-Mesh Streaming

In the peer-mesh layer, **ResumablePeerStream** utilizes the session ID to maintain logical byte-stream continuity across network interruptions. By reusing the same logical stream session identity during reconnects, the system identifies duplicate bytes and calculates precise retransmission requirements without corrupting conversation state.

## Implementation Examples

The following patterns demonstrate how to work with both aspects of session identity in production code.

### Rendering the Title-Bar Identity

This example shows `TitlebarSessionIdentity` consuming the display name while preserving the technical ID for navigation callbacks:

```tsx
import { TitlebarSessionIdentity } from '@maka/ui';

function Header({ sessionId, sessionName, onRename }) {
  return (
    <TitlebarSessionIdentity
      sessionName={sessionName}
      onRenameSession={onRename}
      parentSession={{
        name: 'Root',
        // The UI will call this with the stored ID when the user clicks the left arrow
        onOpen: () => window.maka.sessions.switchTo(sessionId),
      }}
    />
  );
}

```

### Managing Branch Context

When implementing conversation forking, pass the parent session ID through the context layer:

```tsx
import { SessionContextLayer } from '@maka/ui';

function SessionHeader({ sessionId, parent }) {
  return (
    <SessionContextLayer
      sessionName="Chat with Assistant"
      branch={{
        parentSessionId: parent.id,          // ← logical session identifier
        parentSessionName: parent.name,
      }}
      onBranchNavigate={(id) => window.maka.sessions.switchTo(id)}
    />
  );
}

```

### Navigating Revisions

Revision headers require previous and next session IDs to enable timeline navigation:

```tsx
import { SessionContextLayer } from '@maka/ui';

function RevisionHeader({ rev }) {
  return (
    <SessionContextLayer
      sessionName="Chat v2"
      revision={{
        current: rev.index,
        total: rev.total,
        previousSessionId: rev.prevId,
        nextSessionId: rev.nextId,
      }}
      onRevisionNavigate={(id) => window.maka.sessions.switchTo(id)}
    />
  );
}

```

## Summary

- **Session identity in Maka consists of a display name and an opaque ID**, implemented in [`packages/ui/src/titlebar-session-identity.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/titlebar-session-identity.tsx) and referenced throughout the runtime.
- **The session ID is immutable** and used for message routing, branching, and revision tracking via interfaces like `SessionContextBranch` and `SessionContextRevision` in [`packages/ui/src/session-context-layer.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/session-context-layer.tsx).
- **Branch navigation relies on `parentSessionId`** to maintain correct logical pointers when conversations split into parallel threads.
- **Network resumption uses the session ID** as a logical stream identifier to ensure data integrity across reconnects, as documented in [`docs/architecture/peer-mesh-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/peer-mesh-architecture.md).

## Frequently Asked Questions

### What is the difference between session name and session ID in Maka?

The **session name** is a mutable, human-readable string displayed in the UI title bar through the `TitlebarSessionIdentity` component, allowing users to recognize conversations. The **session ID** is an immutable, opaque technical identifier used internally for routing messages, managing branches, and maintaining stream continuity across the peer-mesh network.

### How does Maka handle session identity when conversations branch?

When a conversation branches, Maka stores the original session's ID in the `parentSessionId` field of the `SessionContextBranch` interface (defined at line 41 of [`packages/ui/src/session-context-layer.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/session-context-layer.tsx)). The UI displays the parent's name but uses this ID when invoking `onBranchNavigate()` to ensure navigation targets the correct logical conversation thread rather than potentially ambiguous display names.

### Can session IDs be exposed to end users?

No. According to the implementation in [`titlebar-session-identity.tsx`](https://github.com/apache/maka/blob/main/titlebar-session-identity.tsx) and related components, the raw session ID remains an internal implementation detail. The UI architecture intentionally separates the technical identifier from the presentation layer, exposing only the human-readable `sessionName` to end users while routing all actions through callbacks that internally reference the opaque ID.

### Where is session identity persistence documented in the architecture?

The persistence and resumption of session identity across network interruptions is documented in [`docs/architecture/peer-mesh-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/peer-mesh-architecture.md) at line 170, which describes how **ResumablePeerStream** reuses the logical stream session identity to maintain byte-stream continuity and handle deduplication during reconnects.