​

SPEC-049: Identity & Session Manager Service — Single-Writer for All Identity, Registration, and Routing State

​

Version

​

Status

​

Origin

​

§1 — Audit: Current State

​

1.1 Postgres controller_registrations direct callers

• services/controller_service.py — primary (register, release, get_status, get_prism_status, stamp_heartbeat, sweep_stale)
• services/persona_service.py — whois() reads heartbeat for live state
• services/signal_service.py — _resolve_identity_to_session() reads last_verb_at for engagement
• services/approval_service.py — finds claude_desktop master for approvals
• grpc_runtime/servicer.py — finds session by session_id
• observability/metrics.py — observability counters
• workers/controller_sweep_worker.py — runs sweep_stale() every 60s (10-min stale threshold)

​

1.2 Redis session_store direct callers

• services/controller_service.py — register/release dual-write
• services/persona_service.py — whois() reads get_active_sessions()
• services/signal_service.py — identity-resolution reads + publish_*_event
• routers/session_stream.py — pubsub = store.client.pubsub() directly
• routers/controller.py — admin endpoints
• main.py — startup persona preload

​

1.3 Postgres personas direct callers

• services/persona_service.py — owns CRUD
• routers/personas.py — HTTP wire
• main.py — startup preload

​

1.4 The drift bug, traced

• Redis TTL: ~90s (heartbeat refresh interval × 3, per SPEC-032)
• Postgres controller_sweep_worker: 60s poll, releases rows >10min stale
• Result: an MCP that dies at T=0 disappears from Redis at T+90s, but stays in Postgres controller_registrations (released_at=NULL) until T+10min. controller_status enumerating peers from Postgres reports ghost rows during this window — exactly the Texi×2 / Lafonda×2 pattern we observe today.

​

§2 — Architectural Rule

No code outside the Identity & Session Manager service may read from or write to controller_registrations, personas, or any Redis key matching the session-state namespace (prism:session:*, prism:master:*, prism:sessions:*, prism:personas:*, prism:events:*, prism:engagement:*).

​

§3 — Service Surface (HTTP API)

​

3.1 Sessions

• POST /sm/sessions/register — register or preempt-and-replace. Body: {pid, agent_identity, agent_surface, machine_id, process_pid, session_id, force?, operator_id?, operator_password?}. Atomic: writes Postgres + Redis in one transaction (§4).
• DELETE /sm/sessions/{session_id}?reason=... — release. Atomic.
• POST /sm/sessions/{session_id}/heartbeat — refresh both stores. Out-of-band per SPEC-045 D1 (telecom rule).
• POST /sm/sessions/{session_id}/engagement — stamp last_verb_at.
• GET /sm/sessions/active?pid=... — list active peers (Redis-first, Postgres-backstop on cache miss only).
• GET /sm/sessions/by-identity/{identity}?pid=... — resolve identity → best live session (SPEC-035 §3 ordering: master, then engagement, then heartbeat). Replaces signal_service._resolve_identity_to_session().

​

3.2 Personas

• POST /sm/personas — create. Non-bootstrap-gated (closes the prism_persona_create paradox).
• GET /sm/personas?pid=... — whois (resolved live state included).
• PATCH /sm/personas/{name} — update focus / description / archive.

​

3.3 Election

• POST /sm/elections/{pid}/master/claim — claim master lease.
• POST /sm/elections/{pid}/master/preempt — force-preempt with operator credentials (SPEC-038 §2.4).
• GET /sm/elections/{pid}/master — current master.

​

3.4 Streaming (SPEC-045 plane, hosted by manager)

• WS /sm/stream/{session_id} — replaces /api/v1/session/ws. Manager owns the pubsub fan-out and the new SPEC-037/045 §5.1 delivered_at marking.

​

3.5 Admin

• POST /sm/admin/sweep — manual trigger for the reaper.
• GET /sm/admin/health — Redis + Postgres connectivity.

​

3.6 Identity normalization rule (§3.0 invariant)

​

§4 — Internal Write Coordination

async with manager.write_transaction() as tx:
    pg_change = await tx.postgres(<sql>)
    redis_change = await tx.redis(<command>)
    # Both succeed or both roll back. tx.commit() or tx.rollback().

1. Begin Postgres tx
2. Write Postgres
3. Issue Redis command
4. If Redis fails → Postgres rollback, return error
5. Commit Postgres
6. If Postgres commit fails after Redis succeeded → compensating Redis delete (best effort, logged)

​

§5 — Reaper / Drift Prevention

1. Manager configures Redis with notify-keyspace-events Ex (key expiration events).
2. Internal subscriber listens on __keyevent@*__:expired for keys matching prism:session:*.
3. On expiration → manager extracts session_id from the key → atomically writes Postgres released_at=NOW(), release_reason='heartbeat_expired'.

​

§6 — Migration Plan

​

§7 — Verification

1. CI grep guard: no file outside backend/app/services/session_manager/ imports ControllerRegistration, Persona, or accesses session_store.client private surfaces. Migration adds the rule.
2. Same-machine same-identity duplicate is structurally impossible: second POST /sm/sessions/register for an identity already registered on the same machine_id+process_pid succeeds silently (reconnect path); cross-process collision returns 409 unless force=true. Test against the current Texi×2 / Lafonda×2 state — after migration both collapse to one each.
3. Reaper drift test: kill an MCP, confirm Postgres released_at is stamped within 5 seconds (vs current 10 minutes).
4. POST /signal honesty: send signal to live recipient, response returns delivered=true when WS subscriber confirmed (manager knows live state at POST time).
5. prism_persona_create works pre-bootstrap (paradox closed).
6. Identity case canonicalization: registering “donna” creates the row as “Donna” if a Donna persona exists. Whois returns one row.
7. Manager can be deployed as a separate container; backend FastAPI only needs the manager HTTP URL, not Postgres/Redis directly for session/identity concerns.
8. Existing smokes (SPEC-030 phase1, SPEC-032 redis, SPEC-038 collision, SPEC-044 channels, SPEC-045 envelope + ws_client, SPEC-046 surfaces) all green against the new manager.

​

§8 — Decisions

• D1 (in-tree vs extracted): Phase 1-3 in-tree as a self-contained service module; Phase 4 extracts to its own container. Two-stage delivery — get the architectural rule enforced first, do the packaging cleanup once the rule holds.
• D2 (atomic-write semantics): best-effort coordinated with compensating action + idempotent retry. True 2PC is not worth the complexity for this workload.
• D3 (signal_service ownership): signal_queue table stays with signal_service. Identity-resolution moves to manager. The cut is at “who is online?” (manager) vs “what messages are queued?” (signal).
• D4 (existing reaper retired): controller_sweep_worker removed in Phase 1; replaced by Redis-keyspace-event subscriber inside manager.
• D5 (case canonicalization): enforced at the manager gateway, not via SQL lower() in queries. Wire identity always matches a persona row’s canonical case.

​

§9 — Open Questions

• Q1 (Phase 4 portability transport): HTTP only, or HTTP + WS for the streaming plane already living on the manager? Lean: HTTP for control + same WS endpoint the manager already hosts (no extra layering).
• Q2 (auth between backend and manager when separated): shared service token vs same Bearer the MCP uses? Lean: separate service-to-service token, rotated independently, scoped to the /sm/* namespace.
• Q3 (operator credentials storage): stays on tenants table per SPEC-038, manager reads via Postgres? Or operator-cred APIs themselves are also manager-owned? Lean: operator creds are identity infrastructure → manager owns them too.
• Q4 (gRPC service relation to manager): SPEC-030 gRPC CoordinationStream currently uses controller_registrations. Should it go through manager API in Phase 1, or wait for full retirement per TODO #97? Lean: route through manager in Phase 1 — keeps the rule clean even though the gRPC path is being retired anyway.

​

§10 — What This Spec Replaces

• The “stale-registration reaper” priority item — implemented as part of §5.
• The “same-identity duplicate registrations” priority item — structurally impossible after §4.
• The “prism_persona_create bootstrap paradox” item — closed by §3.2.
• The “POST /signal honesty” item — manager knows live state at POST time per §3.1.
• TODO #97 gRPC retirement — partially eased; manager API replaces the LAN role gRPC was filling.
• The case-insensitive whois fix shipped today (2971f01) — still correct, becomes redundant after §3.6.