mizan/CLAUDE.md

# Mizan — Technical Reference

## What Mizan Is

Mizan is an Application Framework Interface (AFI). One decorator on a server function. Typed client generated. Invalidation automatic. Caching protocol-driven. SSR via subprocess.

Django + React ships first. The protocol is language-agnostic (proven by mizan-ts).

---

## Package Layout

Tree organized by role. Per-framework adapters wrap a single shared kernel; codegen targets the adapter.

```
backends/         server protocol adapters
    mizan-django/    Django adapter
    mizan-fastapi/   FastAPI adapter (RPC + context + invalidation; AFI-common scope)
    mizan-ts/        TypeScript adapter (proves the protocol is language-agnostic)
frontends/        client kernel + per-framework adapters
    mizan-base/      framework-agnostic kernel; owns data, status, error; adapters subscribe
    mizan-react/     React contexts + hooks over the kernel
    mizan-vue/       Vue composables over the kernel
    mizan-svelte/    Svelte stores/runes over the kernel
cores/            shared language-level primitives
    mizan-python/    @client decorator, registry, MWT, HMAC cache keys; consumed by both Python backends
protocol/         protocol-level tooling
    mizan-generate/  codegen — fetches schema from any backend, emits typed React/Vue/Svelte client
workers/          runtime workers / bridges
    mizan-ssr/       Bun subprocess used by the Django template backend
```

---

## The Three Protocols

### 1. RPC Protocol (Anti-REST)

No resources. No CRUD. Functions in, results out.

**Context fetch (reads):**
```
GET /api/mizan/ctx/<context_name>/?param1=val1&param2=val2

200 OK
Cache-Control: no-store
Content-Type: application/json

{
    "user_profile": {"name": "Ryth", "email": "ryth@example.com"},
    "user_orders": [{"id": 1, "total": 100}]
}
```

All functions sharing a context name are bundled into one response. Keys are function names. Values are return values.

**Mutation call (writes):**
```
POST /api/mizan/call/
Content-Type: application/json

{"fn": "update_profile", "args": {"user_id": 5, "name": "Ryth"}}

200 OK
Cache-Control: no-store
X-Mizan-Invalidate: user;user_id=5

{
    "result": {"ok": true},
    "invalidate": [{"context": "user", "params": {"user_id": 5}}]
}
```

### 2. Invalidation-on-Mutation Protocol

Two transports for the same signal. Both are first-class.

**Transport 1 — JSON body** (for RPC/SPA clients):
```json
{"result": {...}, "invalidate": ["user"]}
{"result": {...}, "invalidate": [{"context": "user", "params": {"user_id": 5}}]}
```

**Transport 2 — HTTP header** (for Edge, htmx, view-path functions):
```
X-Mizan-Invalidate: user
X-Mizan-Invalidate: user;user_id=5
X-Mizan-Invalidate: user;user_id=5, notifications
```

Format: comma-separated contexts, semicolon-separated URL-encoded params per context.

**Three-tier auto-scoping** (no developer annotation needed):
1. **Argument name matching:** mutation has `user_id` param, context has `user_id` param → scoped automatically
2. **Auth inference:** Edge-side concern (reads JWT/MWT to extract user identity)
3. **Broad fallback:** invalidate all instances of the context

**Return-type branching** determines which transport:
- Function returns data (dict, BaseModel) → RPC path → JSON body + header
- Function returns HttpResponse (redirect, HTML) → View path → header only

### 3. Frontend-Agnostic Rendering (SSR + PSR)

**SSR** — Django template backend integration. `render(request, 'ProfilePage', props)` calls a persistent Bun subprocess that runs `renderToString`.

**PSR** (Preemptive Static Rendering) — pages re-rendered on mutation, not on request. Edge caches the result. Controlled by the manifest's `render_strategy` field.

**The Bun worker protocol** — JSON-RPC over stdin/stdout:
```
→ {"id": 1, "method": "render", "params": {"component": "ProfilePage", "props": {"userId": 5}}}
← {"id": 1, "html": "<div>...</div>"}
```

Worker stays alive across requests. Django's `SSRBridge` manages the subprocess lifecycle with thread-safe request correlation via message IDs.

---

## The @client Decorator — Full API

```python
from mizan import client, ReactContext, GlobalContext

UserContext = ReactContext('user')
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `context` | `ReactContext \| str \| False` | `False` | Named context for grouping. `False` = standalone function. |
| `affects` | `ReactContext \| str \| list` | `None` | What this mutation invalidates. Mutually exclusive with `context`. |
| `private` | `bool` | `False` | Not client-callable. No RPC endpoint. No codegen. Still in invalidation graph. |
| `route` | `str \| None` | `None` | Mizan-owned URL pattern for view-path functions. |
| `methods` | `list[str] \| None` | `None` | HTTP methods for route. Default: `['GET']` for context, `['POST']` for mutation. |
| `auth` | `bool \| str \| callable \| None` | `None` | Auth requirement: `True`, `'staff'`, `'superuser'`, or `callable(request) -> bool`. |
| `websocket` | `bool` | `False` | Enable WebSocket RPC transport. |
| `rev` | `int` | `0` | Cache revision. Increment to bust cached entries on deploy. |
| `cache` | `int \| False` | (default) | Cache TTL hint. `False` = never cache. Integer = TTL seconds. |

### Usage Patterns

```python
# Global context — auto-mounted at root, SSR-hydrated
@client(context=GlobalContext)
def current_user(request) -> UserShape:
    return UserShape.query(lambda qs: qs.filter(pk=request.user.pk))[0]

# Named context — bundled GET, generates typed hooks
@client(context=UserContext)
def user_profile(request, user_id: int) -> UserShape:
    return UserShape.query(lambda qs: qs.filter(pk=user_id))[0]

@client(context=UserContext)
def user_orders(request, user_id: int) -> list[OrderShape]:
    return OrderShape.query(lambda qs: qs.filter(user_id=user_id))

# Mutation — auto-scoped invalidation (user_id matches)
@client(affects=UserContext)
def update_profile(request, user_id: int, name: str) -> dict:
    request.user.name = name
    request.user.save()
    return {"ok": True}

# Function-level affects — only user_profile refetches
@client(affects='user_profile')
def update_name(request, user_id: int, name: str) -> dict:
    ...

# View-path context — registered in invalidation graph, no codegen
@client(context=UserContext, route='/profile/<user_id>/')
def profile_page(request, user_id: int) -> HttpResponse:
    return render(request, 'profile.html', {...})

# View-path mutation — invalidation via header on the redirect
@client(affects=UserContext, route='/profile/<user_id>/update/', methods=['POST'])
def update_profile_view(request, user_id: int) -> HttpResponse:
    form = ProfileForm(request.POST)
    if form.is_valid():
        form.save()
    return redirect(f'/profile/{user_id}/')

# Private webhook — not client-callable, emits invalidation
@client(affects='subscription', private=True, route='/webhooks/stripe/', methods=['POST'])
def stripe_webhook(request) -> HttpResponse:
    event = json.loads(request.body)
    process_stripe_event(event)
    return HttpResponse(status=200)

# Auth guards
@client(auth=True)
def secret(request) -> dict: ...

@client(auth='staff')
def admin_action(request) -> dict: ...

@client(auth=lambda req: req.user.email.endswith('@company.com'))
def internal_tool(request) -> dict: ...
```

### _meta Dict Structure

After decoration, the function class has `_meta` with these possible keys:

```python
{
    "context": "user",              # context name string (if context=)
    "affects": [                    # normalized affects targets (if affects=)
        {"type": "context", "name": "user"},
        {"type": "function", "name": "user_profile", "context": "user"},
    ],
    "private": True,                # if private=True
    "route": "/webhooks/stripe/",   # if route=
    "methods": ["POST"],            # if route= (defaults applied)
    "view_path": True,              # if return type is HttpResponse
    "websocket": True,              # if websocket=True
    "auth": "required",             # "required" | "staff" | "superuser" | callable
    "rev": 3,                       # if rev=
    "cache": 60,                    # if cache=
    "form": True,                   # if form function
    "form_name": "contact",         # form name
    "form_role": "schema",          # "schema" | "validate" | "submit"
}
```

---

## Cache System

### Required Settings

```python
# settings.py
MIZAN_CACHE_SECRET = "your-32-byte-hmac-signing-key"   # Required for cache
MIZAN_CACHE_REDIS_URL = "redis://localhost:6379/0"      # Required for cache
```

Both must be set. If either is missing, caching is disabled with a warning.

### HMAC Key Derivation

Cache keys are derived from HMAC-SHA256 over a JSON-canonical form:

```python
derive_cache_key(secret, context, params, user_id=None, rev=0) -> str
```

**Canonical form** (the HMAC message):
```json
{"c":"user","p":{"user_id":"5"},"r":0}
```
With optional `"u":"5"` for user-scoped entries.

- `c` = context name
- `p` = sorted params dict (all values stringified)
- `r` = revision number
- `u` = user ID (for auth-scoped cache entries)

**Key format:** `ctx:{context}:{hmac_hex}`
- Example: `ctx:user:605a1ca5ad5994e9b765c8d1b330474c2a0d51a7b8fbbdc402f992da7ba902f6`

**Cross-language conformance:** The TypeScript adapter (`mizan-ts/src/cache/keys.ts`) produces identical keys for identical inputs. Pin tests verify this.

### Cache Operations

```python
from mizan.cache import cache_get, cache_put, cache_purge

# Store
cache_put(secret, backend, "user", {"user_id": "5"}, b'{"name":"Ryth"}')

# Retrieve
data = cache_get(secret, backend, "user", {"user_id": "5"})

# Scoped purge (recomputes HMAC, deletes one key)
cache_purge(backend, "user", params={"user_id": "5"}, secret=secret)

# Broad purge (SCAN by prefix "ctx:user:*")
cache_purge(backend, "user")
```

### Backends

**MemoryCache** — dict-based, for testing. No persistence.

**RedisCache** — production backend.
- Connection pooling (50 max connections)
- 24h default TTL safety net
- Key prefix: `mizan:` (configurable)
- `delete_by_prefix` uses Redis SCAN (1000 keys per batch)
- `delete` uses UNLINK (non-blocking)

### Cache Integration in Dispatch

`context_fetch_view` checks origin-side cache before executing functions. On cache miss, executes functions and stores the result. On mutation, purges affected cache entries based on the invalidation targets.

All HTTP responses emit `Cache-Control: no-store`. Origin-side caching is internal — the HTTP layer never caches at the CDN. Edge caching is managed by Mizan Edge (closed-source Cloudflare Workers) which uses the manifest and MWT tokens.

---

## MWT (Mizan Web Token) and JWT

### Two Token Systems

**JWT** — standard user authentication tokens. Access + refresh pair. Session-tied for revocation.

```python
# settings.py
JWT_PRIVATE_KEY = "your-secret-key"        # Required
JWT_ALGORITHM = "HS256"                     # Default, or RS256 for asymmetric
JWT_ACCESS_TOKEN_EXPIRES_IN = 300           # 5 minutes
JWT_REFRESH_TOKEN_EXPIRES_IN = 604800       # 7 days
JWT_VALIDATE_SESSION = True                 # Check session exists on use
```

JWT claims: `sub` (user ID), `sid` (session key), `staff`, `super`, `type` (access/refresh), `iat`, `exp`.

Session validation: on every JWT use, checks that the session still exists. Logging out destroys the session → immediately revokes all tokens tied to it.

**MWT** — Mizan Web Token. Protocol-owned identity for Edge cache keying. Separate secret from JWT and cache.

```python
# settings.py
MIZAN_MWT_SECRET = "your-mwt-signing-key"  # Separate from JWT_PRIVATE_KEY
MIZAN_MWT_TTL = 300                         # 5 minutes
```

MWT is used by Mizan Edge to derive user-scoped cache keys without exposing the cache secret to the client. The MWT carries claims that Edge needs (user identity, permissions) in a short-lived token that travels on a custom header (`X-Mizan-Token`).

### Secret Separation

Three independent secrets, each with its own blast radius:

| Secret | Setting | Purpose | Compromise Impact |
|--------|---------|---------|-------------------|
| JWT secret | `JWT_PRIVATE_KEY` | User auth tokens | Auth bypass |
| Cache secret | `MIZAN_CACHE_SECRET` | HMAC cache keys | Cache poisoning |
| MWT secret | `MIZAN_MWT_SECRET` | Edge identity tokens | Cache key spoofing |

---

## SSR Implementation

### Django Template Backend

```python
# settings.py
TEMPLATES = [
    {
        'BACKEND': 'mizan.ssr.MizanTemplates',
        'OPTIONS': {
            'worker_path': 'frontend/ssr-worker.tsx',
            'timeout': 5,
        },
    },
]
```

### Usage in Views

```python
from django.shortcuts import render

def profile_page(request, user_id):
    profile = get_user_profile(user_id)
    return render(request, 'ProfilePage', {'profile': profile})
```

`render()` calls `MizanTemplates.get_template('ProfilePage')` which returns a `MizanTemplate`. The template's `render(context)` sends JSON-RPC to the Bun worker.

### SSR Bridge (bridge.py)

- Spawns `bun run <worker_path>` on first render
- Persistent subprocess — stays alive across requests
- JSON-RPC over stdin/stdout with message ID correlation
- Thread-safe: multiple Django workers can call `render()` concurrently
- Auto-restarts on crash
- Waits for `{"id": 0, "ready": true}` before accepting requests

### Bun Worker (worker.tsx)

- Reads newline-delimited JSON from stdin
- Component registry: `registerComponent('ProfilePage', ProfilePage)`
- Calls `renderToString(createElement(Component, props))`
- Returns `{"id": N, "html": "..."}` or `{"id": N, "error": "..."}`
- Health check: `{"method": "ping"}` → `{"pong": true}`

---

## Edge Manifest

Generated by `generate_edge_manifest()` or `python manage.py export_edge_manifest`.

```json
{
    "contexts": {
        "user": {
            "functions": [
                {"name": "user_profile", "path": "rpc"},
                {"name": "profile_page", "path": "view", "route": "/profile/<user_id>/"}
            ],
            "endpoints": ["/api/mizan/ctx/user/"],
            "params": ["user_id"],
            "user_scoped": true,
            "render_strategy": "dynamic_cached",
            "page_routes": ["/profile/<user_id>/"]
        }
    },
    "mutations": {
        "update_profile": {
            "affects": ["user"],
            "auto_scoped_params": ["user_id"]
        },
        "stripe_webhook": {
            "affects": ["subscription"],
            "private": true,
            "route": "/webhooks/stripe/",
            "methods": ["POST"]
        }
    }
}
```

**render_strategy**: `"psr"` (no user-scoped params) or `"dynamic_cached"` (user-scoped). Derived automatically from whether params overlap with `{user_id, user, owner_id, account_id}`.

---

## URL Patterns

```python
# mizan/urls.py
urlpatterns = [
    path("session/", session_init_view),        # GET  — CSRF cookie
    path("call/", function_call_view),           # POST — RPC dispatch
    path("ctx/<str:context_name>/", context_fetch_view),  # GET — bundled context fetch
]
```

Mounted at `/api/mizan/` by convention:
```python
urlpatterns = [
    path("api/mizan/", include("mizan.urls")),
]
```

---

## Codegen — Current State

The codegen is `protocol/mizan-generate/` — framework-agnostic, two-stage. Stage 1 emits the protocol layer (`callXxx` for mutations, `fetchXxx` for context bundles, types). Stage 2 emits per-framework hooks/composables/stores that subscribe to the `mizan-base` kernel.

**What's in place:**

- Function hooks (`useEcho`, `useUserProfile`, etc.) in the React adapter, subscribing to kernel state via `useSyncExternalStore`
- Context hooks for named contexts and `global`
- Channel hooks for WebSocket transport
- Vue and Svelte equivalents (Stage 2 templates compile, but no live-backend example exercises them — see `ISSUES.md` A4)

**What's not yet emitted (the wrapper layer):**

- `<MizanContext>` provider component for React (calls `configure()` and mounts the kernel into the component tree)
- `useMizan()` hook for accessing the kernel from React
- Framework-named error class (e.g. `DjangoError`) wrapping `MizanError` from the kernel
- Vue and Svelte equivalents

The legacy `MizanProvider` in `mizan-react/src/context.tsx` (~750 lines) and the `forms.ts` consumer (~1163 lines) still depend on the pre-kernel API. They're tracked as `ISSUES.md` A1 and A3. Removing them is gated on the wrapper layer above being emitted.

The SSR pipeline is independent of the codegen — it renders whatever components are registered in the Bun worker.