@x-otto/session 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,121 @@
+# @x-otto/session
+
+Agent session pure domain primitives: branching entry tree, compaction storage (append forever), context building, paginated listing, SQLite relational persistence with write leases.
+
+## Install
+
+```bash
+pnpm add @x-otto/session
+```
+
+## Quick Start
+
+```ts
+import { InMemorySession, createSessionStore } from '@x-otto/session'
+
+// In-memory session (entry tree branching)
+const session = new InMemorySession({ model: 'claude-sonnet-4-5' })
+session.append({ role: 'user', content: 'Hello' })
+const fork = session.branch(session.leafId)  // fork at current leaf
+session.recordCompaction({ summary: 'User greeted', replacement: [{ role: 'assistant', content: 'Hi' }] })
+const ctx = session.buildContext()  // entry tree → message array
+
+// Persistent store
+const store = createSessionStore({ kind: 'memory' })
+await store.save('session-1', session.snapshot())
+const loaded = await store.load('session-1')
+```
+
+## Core Architecture
+
+### Entry Tree (InMemorySession)
+
+Message history as an entry tree:
+
+- `SessionEntry<T>` discriminated union: `message` / `compaction` / `clear`
+- `walkBranch()` — traverse along `parentId` chain to `leafId`
+- `recordCompaction(summary, replacement)` — adds a compaction entry with incremental replacement stripping of the prior boundary (RFC-160 D2)
+- `branch(entryId)` — fork by resetting `leafId`; fail-fast if target boundary is stripped
+- `buildContext()` — walks from the most recent boundary (compaction/clear), consuming only its `replacement`
+- `capStoredHistory(max)` — pure in-memory limit (DB retains all data, append-forever)
+- `capStoredHistoryByBytes(maxBytes)` — RFC-178 byte-budget hard gate
+
+### Data Safety Invariants (RFC-159, post-2026-07-13 data loss)
+
+| Invariant | Guard |
+|-----------|-------|
+| save path NEVER deletes `session_entries` rows | No delete code path; `deleteAllEntries` removed entirely |
+| `next_seq` monotonic, never rolls back | Runtime assert: `seq > MAX(seq)` in append transaction |
+| No lease = read-only, no silent overwrites | Save gate throws `SessionWriteLeaseDeniedError` |
+| Stripped state NEVER persisted/checkpointed/forked | `appendEntry` first-line reject + runtime 4-exit assertions + `branch()` fail-fast |
+| Blob absence = fail-fast on assembly | `decodeReplacementFromBlobs` throws on missing blob |
+
+### Relational Persistence (RFC-037 + RFC-159 + RFC-160)
+
+`SqliteSessionRepository` (`SESSION_MIGRATIONS` v1-v5) + `RelationalSessionPersistence` — the production persistence path:
+
+**Write**: incremental append via `entry_id` cursor (fallback to full idempotent append with `ON CONFLICT(session_id, entry_id) DO NOTHING`). Compaction replacement encoded to content-addressed blobs (sha256 → `message_blobs` dedup) before append.
+
+**Read**: tail window (load last N entries when DB exceeds `maxLoadEntries`), inactive replacement stripping (only active boundary retains replacement; new-format rows mark with zero blob reads), dual-format assembly (old inline / new hashes, R6 = assembly-equivalent).
+
+**Hydrate**: `loadEntriesByIds` point query + `hydrateStrippedReplacements` (dual-format). `ReplacementHydrationCapable` capability interface for runtime 4-exit detection (checkpoint, forkSession, forkFromCheckpoint, restore).
+
+### Write Lease (`session-write-lease.ts`)
+
+Per-session single-writer: `O_EXCL` lockfile + token + unref heartbeat + stale takeover (60s). Process exit hook releases synchronously (`/exit -r` zero-wait handoff).
+
+### Thin Persistence Subclasses
+
+InMemory / File / Remote adapters implementing `SessionPersistence<T>`, all thin wrappers over `@x-otto/persistence` backends. File version `@deprecated` (blob legacy). None participate in tail window / stripping / lease.
+
+## Key Files
+
+```
+src/
+  types.ts                          # SessionEntry, SessionContext, SessionPersistence, etc.
+  in-memory-session.ts              # Entry tree + compaction + branch fail-fast
+  session-repository.ts             # SessionRepository interface
+  sqlite-session-repository.ts      # SQLite + MIGRATIONS v1-v5 (message_blobs)
+  relational-session-persistence.ts # Incremental append + lease gate + tail window + hydration
+  relational-bridge.ts              # Snapshot↔rows bridge + dual-format assembly (R6)
+  replacement-blob-codec.ts         # Content-addressed codec (sha256, fail-fast on absent)
+  replacement-hydrator.ts           # Stripped state rehydration + capability interface
+  session-write-lease.ts            # O_EXCL lockfile + token + heartbeat + stale takeover
+  store.ts                          # InMemorySessionStore
+  memory-persistence.ts             # InMemory session persistence adapter
+  file-persistence.ts               # File session persistence adapter (deprecated)
+  remote-persistence.ts             # Remote HTTP session persistence adapter
+  message-bytes.ts                  # RFC-178 estimatedContentBytes + capStoredHistoryByBytes
+  constants.ts                      # Default limits
+  index.ts                          # Barrel exports
+scripts/
+  migrate-replacement-blobs.mjs     # One-time inline→hashes migration (dry-run / apply / verify)
+  replacement-residency-probe.mjs   # Memory residency dual-probe (fixture + production)
+```
+
+## Dependencies
+
+- Internal: `@x-otto/persistence`, `@x-otto/env`
+- External: `better-sqlite3`
+- Consumers: `@x-otto/runtime` (PersistenceSync, SessionManager, TimeTravelController), `@x-otto/coding` (session-pool-factory)
+
+## Testing
+
+```bash
+pnpm --filter @x-otto/session typecheck
+pnpm --filter @x-otto/session build
+pnpm vitest run packages/session/tests/
+```
+
+14 test files including:
+- `rfc159-incident-replay-e2e`: 2026-07-13 data loss incident replay (real disk DB, dual-process, zero-loss)
+- `session-write-lease`: mutual exclusion / stale takeover / fencing
+- `replacement-residency` + `replacement-blob-codec` + `rfc160-integration-e2e`: strip/hydrate/dual-format/migration equivalence
+- `rfc178-content-bytes`: byte budget incremental counter + hard gate
+
+## Related RFCs
+
+- [RFC-037 Relational + append-only](../../docs/rfc/RFC-037-backend-database-relational-append.md)
+- [RFC-159 Append-forever + write lease](../../docs/rfc/RFC-159-session-persistence-append-forever.md) (2026-07-13 postmortem)
+- [RFC-160 Replacement residency](../../docs/rfc/RFC-160-compaction-replacement-residency.md) (blob dedup + residency data)
+- [RFC-178 Content byte budget](../../docs/rfc/RFC-178-content-bytes-cap.md)