gemstone-nexus · Phase 6
Atlas Data Model — Index B Durable Schema
Metadata
| id | doc_id | title | category | source_path | summary | content_hash | indexed_at |
|---|---|---|---|---|---|---|---|
| 5 | DOC-ATLAS-DATA-MODEL | Atlas Data Model — Index B Durable Schema | reference | DevResources/docs/DOC-Atlas-Data-Model.md | vault may still be stubbed. GemStone remains an MCP *client*; these Postgres tables are the durable local Index B mirror (org + practitioner segmented). | 822c9c1f0ec7e7264dd88e3ea7bda2c1c60090c0 | 2026-07-23 14:28:28 |
Content
# Atlas Data Model — Index B Durable Schema
**Status:** Alembic `0008_atlas_vault` (revises `0007_notebook_links`)
**Purpose:** Concrete SQL / JSON contracts for Atlas build while the remote MCP
vault may still be stubbed. GemStone remains an MCP *client*; these Postgres
tables are the durable local Index B mirror (org + practitioner segmented).
Related: [`DOC-Atlas-Index-B.md`](./DOC-Atlas-Index-B.md) (HTTP MCP contract).
## Tenancy
| Claim | Source | Enforcement |
| --- | --- | --- |
| `org_id` | Local JWT (`/api/auth/login`) | API `tenancy.resolve_tenant`; RLS `app.current_org_id` |
| `practitioner_id` | Local JWT / `practitioners` row on signup | Writers + Recents/Search/Atlas recall filters |
| Auth0 | **Deferred** | Same claim shape reserved; no tenant dependency |
Guest / unauthenticated callers cannot read another practitioner’s Atlas segment.
When `AUTH_ENABLED=true`, Recents / Search / notebooks / Index B proxies require
Bearer JWT; org spoofing via `X-Org-Id` is ignored.
## Tables
### `atlas_named_sessions`
Named/dated session index for `/mcp/index-b/index` + `/recall`.
```sql
CREATE TABLE atlas_named_sessions (
entry_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
session_id TEXT NOT NULL,
org_id UUID NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
practitioner_id TEXT NOT NULL,
title TEXT NOT NULL DEFAULT '',
summary TEXT NOT NULL DEFAULT '',
named_label TEXT,
occurred_at TIMESTAMPTZ NOT NULL DEFAULT now(),
tags JSONB NOT NULL DEFAULT '[]',
turns_preview JSONB NOT NULL DEFAULT '[]',
backend TEXT NOT NULL DEFAULT 'local',
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
UNIQUE (org_id, session_id)
);
```
**JSON (Index B upsert mirror):**
```json
{
"session_id": "uuid-or-text",
"org_id": "uuid",
"practitioner_id": "uuid",
"title": "first user utterance…",
"summary": "concatenated turns…",
"named_label": "optional human name",
"occurred_at": "2026-07-22T15:00:00Z",
"tags": [],
"turns_preview": [{"role": "user", "text": "…"}]
}
```
### `atlas_session_turns`
Durable transcript turns (Gemini Live + sovereign + WS). Survives Redis TTL so
Voice Recents restore and Atlas indexing stay available.
```sql
CREATE TABLE atlas_session_turns (
turn_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
session_id TEXT NOT NULL,
org_id UUID NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
practitioner_id TEXT NOT NULL,
turn_seq INT NOT NULL DEFAULT 0,
role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
text TEXT NOT NULL DEFAULT '',
source TEXT NOT NULL DEFAULT 'sovereign',
meta JSONB NOT NULL DEFAULT '{}',
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
```
`source ∈ {sovereign, gemini_live, ws_session, api, restore}`
### `atlas_fine_tuning_signals`
```sql
CREATE TABLE atlas_fine_tuning_signals (
signal_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
org_id UUID NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
practitioner_id TEXT NOT NULL,
session_id TEXT,
signal_type TEXT NOT NULL
CHECK (signal_type IN ('correction', 'rating', 'explicit_feedback')),
original_text TEXT,
corrected_text TEXT,
rating INT CHECK (rating IS NULL OR (rating BETWEEN 1 AND 5)),
context TEXT,
metadata JSONB NOT NULL DEFAULT '{}',
backend TEXT NOT NULL DEFAULT 'local',
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
```
### Notebooks (existing + additive)
- `notebooks` — org-scoped; optional `named_label` (0008)
- `notebook_session_links` — additive links; **never** removes Recents (US-07)
## Writers (Python)
| Path | Module | Notes |
| --- | --- | --- |
| Redis `append_turn` | `app.session.store` → `vault_store.append_turn` | Best-effort durable mirror |
| WS session turns | `app.ws.session` → Index B + vault | Already indexes Atlas stub |
| Gemini Live | `app.ws.gemstone_live` + Voice client | `source=gemini_live` |
| Corrections | `app.atlas.signals.write_fine_tuning_signal` | Dual-write PG + MCP |
| Named index | `vault_store.upsert_named_session` | On turn / end |
## API surface (practitioner-scoped)
| Method | Path | Scope |
| --- | --- | --- |
| GET | `/api/sessions?limit=40` | Recents for JWT org + practitioner |
| GET | `/api/sessions/{id}` | Restore buffer; Atlas turns fallback |
| GET | `/api/sessions/{id}/turns` | Durable turns for restore |
| POST | `/api/search/inferenced` | Atlas + Recents + notebooks for prac |
| CRUD | `/api/notebooks*` | Org (+ practitioner on create) |
| GET | `/api/notebooks/{id}` | Detail + `sessions[{session_id,title,linked_at}]` for Agent open |
| POST | `/api/notebooks/{id}/link` | Additive session link (Recents untouched) |
| * | `/mcp/atlas/*` | Index B proxy; JWT org/prac |
## RLS
All three Atlas tables ENABLE ROW LEVEL SECURITY with
`org_id::text = current_setting('app.current_org_id')`. Application filters by
`practitioner_id` for segment isolation within an org.
## Auth (local JWT — no Auth0 dependency)
```
POST /api/auth/signup → provisions org + practitioner + user, returns JWT
POST /api/auth/login → JWT { sub, org_id, practitioner_id, role, email }
GET /api/auth/me → current principal
```
Set on live: `AUTH_ENABLED=true`, `AUTH_ALLOW_SIGNUP=true`, strong `JWT_SECRET`.