# How Apache Maka Prevents Multiple Writers and Conflicting Session State

> Apache Maka prevents multiple writers and conflicting session state using a single-writer-per-lease architecture, brand symbols, WeakSet registration, and centralized storage writer composition. Learn how Maka ensures data inte...

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

---

**Apache Maka prevents multiple writers and conflicting session state by implementing a strict single-writer-per-lease architecture using brand symbols, WeakSet registration, and centralized storage writer composition.**

The Apache Maka repository manages complex session state across UI components, runtime hosts, and background services. To prevent race conditions and conflicting updates, the storage layer enforces that only one authenticated writer can mutate a session at any given time. This article examines the exact mechanisms—from writer branding to lease-based locking—implemented in the source code.

## Writer Identity and Brand Symbols

Apache Maka assigns a unique identity to every writer type through **brand symbols**. These symbols act as runtime type guards that distinguish legitimate writers from stray objects attempting unauthorized access.

In [`packages/storage/src/usage-stores.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/usage-stores.ts), the system declares a unique symbol `writerBrand` that marks authentic interactive usage writers:

```typescript
// packages/storage/src/usage-stores.ts
const writerBrand = Symbol('interactiveUsageStoresWriter');

interface InteractiveUsageStoresWriter {
  [writerBrand]: true;
  // ... writer methods
}

```

The same pattern appears in [`packages/storage/src/task-ledger-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/task-ledger-authority.ts) and [`packages/storage/src/shell-run-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/shell-run-authority.ts), where distinct brand symbols isolate task ledger and shell run writers respectively. This branding ensures that **writer identity** is unforgeable and type-safe at runtime.

## Active Writer Registration with WeakSet

To enforce exclusive access, Apache Maka maintains a **WeakSet** named `writers` that tracks every currently active writer instance. When `createInteractiveWriterFacade` opens a new writer, the system immediately registers it:

```typescript
// packages/storage/src/usage-stores.ts
writers.add(writer);
writerByLease.set(lease, writer);

```

Because a `WeakSet` can contain only one instance of a given object, any attempt to register a second writer for the same lease automatically fails. If code attempts to create a duplicate writer for an active lease, the brand check combined with WeakSet membership verification throws an explicit error: `Expected an authentic interactive usage writer`.

## Lease-Based Write Locking

The storage layer maps each lease to exactly one writer using two **WeakMap** structures:

1. **`writerByLease`** – Associates a lease object with its active writer
2. **`writerOpeningByLease`** – Tracks pending asynchronous writer creation to prevent race conditions during initialization

```typescript
// packages/storage/src/usage-stores.ts
const writerByLease = new WeakMap<object, InteractiveUsageStoresWriter>();
const writerOpeningByLease = new WeakMap<object, Promise<InteractiveUsageStoresWriter>>();

```

When two callers simultaneously request a writer for the same lease, the second caller discovers the existing promise in `writerOpeningByLease` and awaits it rather than spawning a competing writer. This guarantees **atomic writer creation** even under concurrent access.

## Storage Writer Composition

The `composeWriters` function in [`packages/storage/src/storage-writer-composition.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/storage-writer-composition.ts) orchestrates the entire writer lifecycle. It opens writers in a deterministic order—first the runtime-policy writer, then all ancillary stores—and registers a cleanup callback that closes every writer when the lease terminates:

```typescript
// packages/storage/src/storage-writer-composition.ts
await composeWriters(lease, async (open) => {
  const policyWriter = await open(runtimePolicyStore);
  const usageWriter = await open(usageStore);
  const taskWriter = await open(taskLedgerStore);
  
  return { policyWriter, usageWriter, taskWriter };
});

```

By centralizing writer acquisition through this composition layer, Apache Maka ensures that **only the writers opened within the compose callback** can access storage during the lease lifetime. This eliminates external code paths from obtaining unauthorized write handles.

## Session Store Conflict Detection

As a final safeguard, [`packages/storage/src/session-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/session-store.ts) validates writer identity before accepting state mutations. The store retains the session name provided by the writer that successfully claimed the lease:

```typescript
// packages/storage/src/session-store.ts
if (sessionStore.name !== writerProvidedName) {
  throw new Error('Session keeps whichever name the writer that won gave it.');
}

```

This check prevents a writer created for a different session—or a stale writer from a previous lease—from corrupting current session state. The enforcement ensures **session-to-writer affinity** throughout the lease duration.

## Summary

- **Writer brand symbols** provide unforgeable runtime identity for each writer type across [`usage-stores.ts`](https://github.com/apache/maka/blob/main/usage-stores.ts), [`task-ledger-authority.ts`](https://github.com/apache/maka/blob/main/task-ledger-authority.ts), and [`shell-run-authority.ts`](https://github.com/apache/maka/blob/main/shell-run-authority.ts).
- **WeakSet registration** physically prevents duplicate writer instances from existing simultaneously for the same lease.
- **WeakMap tracking** maps leases to single writers and deduplicates concurrent creation attempts via `writerOpeningByLease`.
- **Storage writer composition** centralizes lifecycle management, opening writers atomically and closing them on lease termination.
- **Session store validation** performs final conflict detection by verifying the claiming writer matches the session's assigned writer.

## Frequently Asked Questions

### How does Apache Maka handle concurrent attempts to create writers for the same lease?

When concurrent code paths attempt to create writers simultaneously, the `writerOpeningByLease` WeakMap stores the pending promise from the first attempt. Subsequent callers retrieve this existing promise and await its resolution rather than creating competing writers. This guarantees that all callers receive the identical writer instance, preventing multiple writers from entering the system.

### What prevents a malicious or buggy component from spoofing a writer identity?

Writer identity relies on **unique symbols** (`writerBrand`) that are module-scoped and cannot be replicated by external code. The `writers` WeakSet contains the actual writer objects, and authentication checks verify both the presence of the brand symbol and membership in the WeakSet. Since symbols are unique and unguessable, and WeakSet references cannot be forged, the system cryptographically isolates legitimate writers.

### Why does Apache Maka use WeakSet and WeakMap instead of regular Sets and Maps?

Apache Maka uses **WeakSet** and **WeakMap** specifically to avoid memory leaks. Writers and leases are transient objects tied to component lifecycles. When a lease ends and the writer closes, dropping all references allows the garbage collector to reclaim memory automatically—unlike regular Sets/Maps, which would retain entries until explicitly deleted.

### Which source files contain the core logic for preventing conflicting session state?

The primary enforcement resides in [`packages/storage/src/usage-stores.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/usage-stores.ts), [`packages/storage/src/task-ledger-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/task-ledger-authority.ts), and [`packages/storage/src/shell-run-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/shell-run-authority.ts) for writer branding; [`packages/storage/src/storage-writer-composition.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/storage-writer-composition.ts) for lease orchestration; and [`packages/storage/src/session-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/session-store.ts) for final conflict detection at the session layer.