Updates

pear-platform/hyper-pear-runtime-session/docs/api.md

@@ -1,26 +1,97 @@
 # API: hyper-pear-runtime-session
 
-**Protocol:** `pear-runtime-session/v1` · **Export:** `HyperPearRuntimeSession`
+**Protocol:** `pear-runtime-session/v1` · **Export:** `HyperPearRuntimeSession`, `HyperP2PPearRuntimeSession`, `PROTOCOL`
+
+## Overview
+
+Tracks Pear runtime sessions in-process with opaque ids, optional metadata, and active/ended lifecycle. Local-only — no gossip; suitable for correlating logs and bundle operations within one Bare host.
+
+## Constructor
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| _(none)_ | — | — | `opts = {}` unused |
 
 ## Methods
 
-### `startSession(...)`
+### `startSession(meta?)`
 
-Domain API.
+Creates session with random 8-byte hex id from hashed timestamp + sequence.
 
-### `endSession(...)`
+- **Returns:** `{ id, meta, startedAt, endedAt: null, active: true }`
+- **Emits:** `started`
 
-Domain API.
+### `endSession(id)`
 
-### `activeSessions(...)`
+Marks session ended.
 
-Domain API.
+- **Returns:** updated session
+- **Throws:** `session not found: ${id}`; `session already ended: ${id}`
+- **Emits:** `ended`
 
+### `activeSessions()`
 
-### `getStats()` / `ready()` / `close()`
+- **Returns:** array of sessions where `active === true`
 
-Lifecycle helpers.
+### `getSession(id)`
+
+- **Returns:** session or `null`
+- **Throws:** `assertNonEmpty` on `id`
+
+### `ready()` / `close()`
+
+Immediate `ready()`. `close()` emits `closed`.
+
+## Events
+
+| Event | Payload |
+|-------|---------|
+| `started` | session object |
+| `ended` | session object |
+| `closed` | — |
+
+## getStats()
+
+| Field | Meaning |
+|-------|---------|
+| `started` / `ended` | lifecycle counters |
+| `total` | all sessions in map |
+| `active` | count of active sessions |
+| `protocol` | `pear-runtime-session/v1` |
+| `mode` | `local` |
+
+## Wire
+
+No wire messages.
+
+| type | fields | notes |
+|------|--------|-------|
+| — | — | local-only |
+
+## Errors
+
+`assertNonEmpty` for id lookups. Session state errors use exact `Error` strings above.
+
+See [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 
 ## P2P
 
-Local-only.
+Not used. Pair with gossip modules only at application layer (attach session id to gossip meta).
+
+## Testing
+
+```bash
+cd modules/pear-platform/hyper-pear-runtime-session && npm test
+```
+
+## Composition
+
+`hyper-bare-bundle-bridge`, `hyper-pear-update-gossip`, `hyper-p2p-session-rotation` for token rotation after session end.
+
+## Example
+
+See [`examples/basic.js`](../examples/basic.js).
+
+## See also
+
+[`docs/architecture.md`](architecture.md).

pear-platform/hyper-pear-runtime-session/docs/architecture.md

@@ -1,11 +1,31 @@
 # Architecture: hyper-pear-runtime-session
 
+**Protocol:** `pear-runtime-session/v1` · **Category:** pear-platform · **Mode:** local-only
+
+```mermaid
+flowchart LR
+  App --> Sess[HyperPearRuntimeSession]
+  Sess --> Map[_sessions Map]
+```
+
 ## Wire messages
 
-| type | fields | direction | behavior |
-|------|--------|-----------|----------|
-| — | — | — | Local-only |
+| type | direction | fields | behavior |
+|------|-----------|--------|----------|
+| — | — | — | No network protocol; id constant for module registry |
 
-## State
+## State model
 
-In-memory structures; gossip via `initModuleSwarm` / `gossipSend` when P2P enabled.
+- `_sessions`: `Map<id, session>`
+- `_seq`: monotonic counter for id generation
+- `_stats`: `started`, `ended`
+
+## Sequence
+
+1. `startSession` → hash-based id → `emit('started')`
+2. `endSession` → flip `active`, set `endedAt`
+3. `getStats` aggregates active count
+
+## Composition
+
+`hyper-bare-bundle-bridge`, `hyper-pear-update-gossip`.