gemstone-nexus · Phase 6

Atlas Data Model — Index B Durable Schema

← Documents

Metadata

iddoc_idtitlecategorysource_pathsummarycontent_hashindexed_at
5DOC-ATLAS-DATA-MODELAtlas Data Model — Index B Durable SchemareferenceDevResources/docs/DOC-Atlas-Data-Model.mdvault may still be stubbed. GemStone remains an MCP *client*; these Postgres tables are the durable local Index B mirror (org + practitioner segmented).822c9c1f0ec7e7264dd88e3ea7bda2c1c60090c02026-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`.