docs: roll-up projection contract revision 3 (terra re-review residuals)

F2: partial-scope witnesses reconstructed at platform-project and
estate sibling levels, where chain grants can differ; the
workspace-sibling construction is stated non-constructible under
contract 1 grant targets.
F3: section 2.5 defines one field-exact recursive roll-up node record
(id/type/name/totals/children at every depth, required children array,
empty at workspaces, ascending-id ordering, no wrapper); whole-result
rules moved to section 2.6 at section scope; section 6.7 witness
asserts the recursive shape.
F6: fixture assigns workspaces to named platform-projects; grant-level
cases limited to the three levels contract 1 defines, workspace access
covered by membership with the no-workspace-grant fact stated.

apps/web/src/routes.tsx

@@ -13,8 +13,9 @@ import {
   TasksRouteErrorBoundary,
 } from '@/spa/pages/resource-route-error-boundaries';
 import { TasksPage } from '@/spa/pages/tasks';
-import { AuthGuard, GuestGuard } from '@/spa/guards';
-import { Placeholder } from '@/spa/placeholder';
+import { SettingsPage } from '@/spa/pages/settings';
+import { AdminPage } from '@/spa/pages/admin';
+import { AdminGuard, AuthGuard, GuestGuard } from '@/spa/guards';
 
 function GuestLayout(): ReactElement {
   return (
@@ -56,8 +57,11 @@ export const routes: RouteObject[] = [
         errorElement: <ProjectDetailRouteErrorBoundary />,
       },
       { path: '/tasks', element: <TasksPage />, errorElement: <TasksRouteErrorBoundary /> },
-      { path: '/settings', element: <Placeholder title="Settings" /> },
-      { path: '/admin', element: <Placeholder title="Admin" /> },
+      { path: '/settings', element: <SettingsPage /> },
+      {
+        element: <AdminGuard />,
+        children: [{ path: '/admin', element: <AdminPage /> }],
+      },
     ],
   },
 ];

apps/web/src/spa/guards.tsx

@@ -21,3 +21,23 @@ export function AuthGuard(): ReactElement {
 
   return session ? <Outlet /> : <Navigate to="/login" replace />;
 }
+
+export function AdminGuard(): ReactElement {
+  const { data: session, isPending } = useSession();
+
+  if (isPending) {
+    return (
+      <div className="flex min-h-screen items-center justify-center">
+        <div className="text-sm text-text-muted">Loading...</div>
+      </div>
+    );
+  }
+
+  if (!session) {
+    return <Navigate to="/login" replace />;
+  }
+
+  const user = session.user as typeof session.user & { role?: string };
+
+  return user.role === 'admin' ? <Outlet /> : <Navigate to="/" replace />;
+}

apps/web/src/spa/pages/admin.spec.tsx

@@ -0,0 +1,206 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { createMemoryRouter, RouterProvider, type RouteObject } from 'react-router-dom';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+const { apiMock, useSessionMock } = vi.hoisted(() => ({
+  apiMock: vi.fn(),
+  useSessionMock: vi.fn(),
+}));
+
+vi.mock('@/lib/api', () => ({
+  api: apiMock,
+}));
+
+vi.mock('@/lib/auth-client', () => ({
+  useSession: useSessionMock,
+  authClient: {},
+}));
+
+import { AdminPage } from './admin';
+import { AdminGuard } from '@/spa/guards';
+
+const userFixtures = {
+  users: [
+    {
+      id: 'u-admin',
+      name: 'Ada Admin',
+      email: '[email protected]',
+      role: 'admin',
+      banned: false,
+      banReason: null,
+      createdAt: '2026-08-01T00:00:00.000Z',
+      updatedAt: '2026-08-01T00:00:00.000Z',
+    },
+    {
+      id: 'u-member',
+      name: 'Mel Member',
+      email: '[email protected]',
+      role: 'member',
+      banned: true,
+      banReason: 'spam',
+      createdAt: '2026-08-02T00:00:00.000Z',
+      updatedAt: '2026-08-02T00:00:00.000Z',
+    },
+  ],
+  total: 2,
+};
+
+let root: Root | null = null;
+let container: HTMLDivElement;
+
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
+    configurable: true,
+    value: true,
+  });
+});
+
+afterAll(() => {
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+});
+
+afterEach(async () => {
+  await act(async () => {
+    root?.unmount();
+  });
+  document.body.replaceChildren();
+  root = null;
+  apiMock.mockReset();
+  useSessionMock.mockReset();
+});
+
+async function renderAdminRoute(): Promise<void> {
+  const routes: RouteObject[] = [
+    {
+      element: <AdminGuard />,
+      children: [{ path: '/admin', element: <AdminPage /> }],
+    },
+    { path: '/', element: <div>home page</div> },
+    { path: '/login', element: <div>login page</div> },
+  ];
+  const router = createMemoryRouter(routes, { initialEntries: ['/admin'] });
+  container = document.createElement('div');
+  document.body.append(container);
+  root = createRoot(container);
+
+  await act(async () => {
+    root?.render(<RouterProvider router={router} />);
+  });
+}
+
+function sessionWithRole(role: string | undefined): { data: unknown; isPending: boolean } {
+  return {
+    data: { user: { id: 'u-1', name: 'Test', email: '[email protected]', role } },
+    isPending: false,
+  };
+}
+
+describe('AdminGuard', () => {
+  it('redirects unauthenticated visitors to /login', async () => {
+    useSessionMock.mockReturnValue({ data: null, isPending: false });
+
+    await renderAdminRoute();
+
+    expect(container.textContent).toContain('login page');
+    expect(apiMock).not.toHaveBeenCalled();
+  });
+
+  it('redirects non-admin users to /', async () => {
+    useSessionMock.mockReturnValue(sessionWithRole('member'));
+
+    await renderAdminRoute();
+
+    expect(container.textContent).toContain('home page');
+    expect(apiMock).not.toHaveBeenCalled();
+  });
+
+  it('renders the admin page for admin users', async () => {
+    useSessionMock.mockReturnValue(sessionWithRole('admin'));
+    apiMock.mockResolvedValueOnce(userFixtures);
+
+    await renderAdminRoute();
+
+    expect(container.textContent).toContain('Admin Panel');
+  });
+});
+
+describe('AdminPage users tab', () => {
+  it('lists users with role and ban status after load', async () => {
+    useSessionMock.mockReturnValue(sessionWithRole('admin'));
+    apiMock.mockResolvedValueOnce(userFixtures);
+
+    await renderAdminRoute();
+
+    expect(apiMock).toHaveBeenCalledWith('/api/admin/users');
+    expect(container.textContent).toContain('Ada Admin');
+    expect(container.textContent).toContain('Mel Member');
+    expect(container.textContent).toContain('Banned');
+    expect(container.textContent).toContain('2 user(s)');
+  });
+
+  it('shows the load error with a retry control', async () => {
+    useSessionMock.mockReturnValue(sessionWithRole('admin'));
+    apiMock.mockRejectedValueOnce(new Error('gateway unavailable'));
+
+    await renderAdminRoute();
+
+    expect(container.textContent).toContain('gateway unavailable');
+
+    apiMock.mockResolvedValueOnce(userFixtures);
+    const retry = [...container.querySelectorAll('button')].find((b) =>
+      b.textContent?.includes('Retry'),
+    );
+    expect(retry).toBeTruthy();
+    await act(async () => {
+      retry?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    expect(container.textContent).toContain('Ada Admin');
+  });
+
+  it('posts to the ban endpoint and reloads on Ban', async () => {
+    useSessionMock.mockReturnValue(sessionWithRole('admin'));
+    apiMock.mockResolvedValue(userFixtures);
+
+    await renderAdminRoute();
+
+    const banButton = [...container.querySelectorAll('button')].find(
+      (b) => b.textContent === 'Ban',
+    );
+    expect(banButton).toBeTruthy();
+    await act(async () => {
+      banButton?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    expect(apiMock).toHaveBeenCalledWith('/api/admin/users/u-admin/ban', { method: 'POST' });
+  });
+});
+
+describe('AdminPage health tab', () => {
+  it('loads health status when the tab is opened', async () => {
+    useSessionMock.mockReturnValue(sessionWithRole('admin'));
+    apiMock.mockResolvedValueOnce(userFixtures).mockResolvedValueOnce({
+      status: 'ok',
+      database: { status: 'ok', latencyMs: 3 },
+      cache: { status: 'ok', latencyMs: 1 },
+      agentPool: { activeSessions: 2 },
+      providers: [{ id: 'ollama', name: 'Ollama', available: true, modelCount: 4 }],
+      checkedAt: '2026-08-26T00:00:00.000Z',
+    });
+
+    await renderAdminRoute();
+
+    const healthTab = [...container.querySelectorAll('button')].find((b) =>
+      b.textContent?.includes('System Health'),
+    );
+    await act(async () => {
+      healthTab?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    expect(apiMock).toHaveBeenCalledWith('/api/admin/health');
+    expect(container.textContent).toContain('Database (PostgreSQL)');
+    expect(container.textContent).toContain('Active sessions: 2');
+    expect(container.textContent).toContain('4 models');
+  });
+});

apps/web/src/spa/pages/admin.tsx

@@ -0,0 +1,522 @@
+import { useEffect, useState, useCallback } from 'react';
+import { api } from '@/lib/api';
+import { cn } from '@/lib/cn';
+
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+interface UserDto {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+  banned: boolean;
+  banReason: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface UserListDto {
+  users: UserDto[];
+  total: number;
+}
+
+interface ServiceStatusDto {
+  status: 'ok' | 'error';
+  latencyMs?: number;
+  error?: string;
+}
+
+interface ProviderStatusDto {
+  id: string;
+  name: string;
+  available: boolean;
+  modelCount: number;
+}
+
+interface HealthStatusDto {
+  status: 'ok' | 'degraded' | 'error';
+  database: ServiceStatusDto;
+  cache: ServiceStatusDto;
+  agentPool: { activeSessions: number };
+  providers: ProviderStatusDto[];
+  checkedAt: string;
+}
+
+// ── Admin Page ─────────────────────────────────────────────────────────────────
+
+// Route-level access control lives in AdminGuard (spa/guards.tsx); this page
+// assumes an authenticated admin session.
+export function AdminPage(): React.ReactElement {
+  const [activeTab, setActiveTab] = useState<'users' | 'health'>('users');
+
+  return (
+    <div className="mx-auto max-w-5xl space-y-6">
+      <div className="flex items-center justify-between">
+        <h1 className="text-2xl font-semibold text-text-primary">Admin Panel</h1>
+      </div>
+
+      <div className="flex gap-1 border-b border-surface-border">
+        {(['users', 'health'] as const).map((tab) => (
+          <button
+            key={tab}
+            type="button"
+            onClick={() => setActiveTab(tab)}
+            className={cn(
+              'px-4 py-2 text-sm font-medium capitalize transition-colors',
+              activeTab === tab
+                ? 'border-b-2 border-blue-500 text-blue-400'
+                : 'text-text-secondary hover:text-text-primary',
+            )}
+          >
+            {tab === 'users' ? 'User Management' : 'System Health'}
+          </button>
+        ))}
+      </div>
+
+      {activeTab === 'users' ? <UsersTab /> : <HealthTab />}
+    </div>
+  );
+}
+
+// ── Users Tab ──────────────────────────────────────────────────────────────────
+
+function UsersTab(): React.ReactElement {
+  const [users, setUsers] = useState<UserDto[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [showCreate, setShowCreate] = useState(false);
+
+  const loadUsers = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await api<UserListDto>('/api/admin/users');
+      setUsers(data.users);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to load users');
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void loadUsers();
+  }, [loadUsers]);
+
+  async function handleRoleToggle(user: UserDto): Promise<void> {
+    const newRole = user.role === 'admin' ? 'member' : 'admin';
+    try {
+      await api(`/api/admin/users/${user.id}/role`, {
+        method: 'PATCH',
+        body: { role: newRole },
+      });
+      await loadUsers();
+    } catch (err) {
+      alert(err instanceof Error ? err.message : 'Failed to update role');
+    }
+  }
+
+  async function handleBanToggle(user: UserDto): Promise<void> {
+    const endpoint = user.banned ? 'unban' : 'ban';
+    try {
+      await api(`/api/admin/users/${user.id}/${endpoint}`, { method: 'POST' });
+      await loadUsers();
+    } catch (err) {
+      alert(err instanceof Error ? err.message : 'Failed to update ban status');
+    }
+  }
+
+  async function handleDelete(user: UserDto): Promise<void> {
+    if (!confirm(`Delete user ${user.email}? This cannot be undone.`)) return;
+    try {
+      await api(`/api/admin/users/${user.id}`, { method: 'DELETE' });
+      await loadUsers();
+    } catch (err) {
+      alert(err instanceof Error ? err.message : 'Failed to delete user');
+    }
+  }
+
+  if (loading) {
+    return <p className="text-sm text-text-muted">Loading users...</p>;
+  }
+
+  if (error) {
+    return (
+      <div className="rounded-lg border border-red-500/30 bg-red-500/10 p-4">
+        <p className="text-sm text-red-400">{error}</p>
+        <button
+          type="button"
+          onClick={() => void loadUsers()}
+          className="mt-2 text-xs text-red-300 underline hover:no-underline"
+        >
+          Retry
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-between">
+        <p className="text-sm text-text-muted">{users.length} user(s)</p>
+        <button
+          type="button"
+          onClick={() => setShowCreate(true)}
+          className="rounded-md bg-blue-600 px-3 py-1.5 text-sm text-white transition-colors hover:bg-blue-700"
+        >
+          + New User
+        </button>
+      </div>
+
+      {showCreate && (
+        <CreateUserForm
+          onCancel={() => setShowCreate(false)}
+          onCreated={() => {
+            setShowCreate(false);
+            void loadUsers();
+          }}
+        />
+      )}
+
+      {users.length === 0 ? (
+        <div className="rounded-lg border border-surface-border bg-surface-card p-6 text-center">
+          <p className="text-sm text-text-muted">No users found</p>
+        </div>
+      ) : (
+        <div className="overflow-hidden rounded-lg border border-surface-border">
+          <table className="w-full">
+            <thead>
+              <tr className="border-b border-surface-border bg-surface-elevated text-left text-xs text-text-muted">
+                <th className="px-4 py-2 font-medium">Name / Email</th>
+                <th className="px-4 py-2 font-medium">Role</th>
+                <th className="hidden px-4 py-2 font-medium md:table-cell">Status</th>
+                <th className="hidden px-4 py-2 font-medium md:table-cell">Created</th>
+                <th className="px-4 py-2 font-medium">Actions</th>
+              </tr>
+            </thead>
+            <tbody>
+              {users.map((user) => (
+                <tr key={user.id} className="border-b border-surface-border last:border-b-0">
+                  <td className="px-4 py-3">
+                    <div className="text-sm font-medium text-text-primary">{user.name}</div>
+                    <div className="text-xs text-text-muted">{user.email}</div>
+                  </td>
+                  <td className="px-4 py-3">
+                    <span
+                      className={cn(
+                        'inline-flex rounded-full px-2 py-0.5 text-xs font-medium',
+                        user.role === 'admin'
+                          ? 'bg-purple-500/20 text-purple-400'
+                          : 'bg-surface-elevated text-text-secondary',
+                      )}
+                    >
+                      {user.role}
+                    </span>
+                  </td>
+                  <td className="hidden px-4 py-3 md:table-cell">
+                    {user.banned ? (
+                      <span className="inline-flex rounded-full bg-red-500/20 px-2 py-0.5 text-xs font-medium text-red-400">
+                        Banned
+                      </span>
+                    ) : (
+                      <span className="inline-flex rounded-full bg-green-500/20 px-2 py-0.5 text-xs font-medium text-green-400">
+                        Active
+                      </span>
+                    )}
+                  </td>
+                  <td className="hidden px-4 py-3 text-xs text-text-muted md:table-cell">
+                    {new Date(user.createdAt).toLocaleDateString()}
+                  </td>
+                  <td className="px-4 py-3">
+                    <div className="flex items-center gap-2">
+                      <button
+                        type="button"
+                        onClick={() => void handleRoleToggle(user)}
+                        className="text-xs text-blue-400 hover:text-blue-300"
+                        title={user.role === 'admin' ? 'Demote to member' : 'Promote to admin'}
+                      >
+                        {user.role === 'admin' ? 'Demote' : 'Promote'}
+                      </button>
+                      <button
+                        type="button"
+                        onClick={() => void handleBanToggle(user)}
+                        className={cn(
+                          'text-xs',
+                          user.banned
+                            ? 'text-green-400 hover:text-green-300'
+                            : 'text-yellow-400 hover:text-yellow-300',
+                        )}
+                      >
+                        {user.banned ? 'Unban' : 'Ban'}
+                      </button>
+                      <button
+                        type="button"
+                        onClick={() => void handleDelete(user)}
+                        className="text-xs text-red-400 hover:text-red-300"
+                      >
+                        Delete
+                      </button>
+                    </div>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ── Create User Form ──────────────────────────────────────────────────────────
+
+interface CreateUserFormProps {
+  onCancel: () => void;
+  onCreated: () => void;
+}
+
+function CreateUserForm({ onCancel, onCreated }: CreateUserFormProps): React.ReactElement {
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [role, setRole] = useState('member');
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function handleSubmit(e: React.FormEvent): Promise<void> {
+    e.preventDefault();
+    setSubmitting(true);
+    setError(null);
+    try {
+      await api('/api/admin/users', {
+        method: 'POST',
+        body: { name, email, password, role },
+      });
+      onCreated();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to create user');
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <div className="rounded-lg border border-surface-border bg-surface-card p-4">
+      <h3 className="mb-3 text-sm font-medium text-text-primary">Create New User</h3>
+      <form onSubmit={(e) => void handleSubmit(e)} className="space-y-3">
+        {error && <p className="text-xs text-red-400">{error}</p>}
+        <div className="grid grid-cols-2 gap-3">
+          <div>
+            <label className="mb-1 block text-xs text-text-muted">Name</label>
+            <input
+              type="text"
+              required
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+              className="w-full rounded-md border border-surface-border bg-surface-elevated px-3 py-1.5 text-sm text-text-primary focus:outline-none focus:ring-1 focus:ring-blue-500"
+            />
+          </div>
+          <div>
+            <label className="mb-1 block text-xs text-text-muted">Email</label>
+            <input
+              type="email"
+              required
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              className="w-full rounded-md border border-surface-border bg-surface-elevated px-3 py-1.5 text-sm text-text-primary focus:outline-none focus:ring-1 focus:ring-blue-500"
+            />
+          </div>
+          <div>
+            <label className="mb-1 block text-xs text-text-muted">Password</label>
+            <input
+              type="password"
+              required
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              className="w-full rounded-md border border-surface-border bg-surface-elevated px-3 py-1.5 text-sm text-text-primary focus:outline-none focus:ring-1 focus:ring-blue-500"
+            />
+          </div>
+          <div>
+            <label className="mb-1 block text-xs text-text-muted">Role</label>
+            <select
+              value={role}
+              onChange={(e) => setRole(e.target.value)}
+              className="w-full rounded-md border border-surface-border bg-surface-elevated px-3 py-1.5 text-sm text-text-primary focus:outline-none focus:ring-1 focus:ring-blue-500"
+            >
+              <option value="member">member</option>
+              <option value="admin">admin</option>
+            </select>
+          </div>
+        </div>
+        <div className="flex justify-end gap-2">
+          <button
+            type="button"
+            onClick={onCancel}
+            className="rounded-md px-3 py-1.5 text-sm text-text-muted hover:text-text-primary"
+          >
+            Cancel
+          </button>
+          <button
+            type="submit"
+            disabled={submitting}
+            className="rounded-md bg-blue-600 px-3 py-1.5 text-sm text-white hover:bg-blue-700 disabled:opacity-50"
+          >
+            {submitting ? 'Creating...' : 'Create'}
+          </button>
+        </div>
+      </form>
+    </div>
+  );
+}
+
+// ── Health Tab ────────────────────────────────────────────────────────────────
+
+function HealthTab(): React.ReactElement {
+  const [health, setHealth] = useState<HealthStatusDto | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const loadHealth = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await api<HealthStatusDto>('/api/admin/health');
+      setHealth(data);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to load health');
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void loadHealth();
+  }, [loadHealth]);
+
+  if (loading) {
+    return <p className="text-sm text-text-muted">Loading health status...</p>;
+  }
+
+  if (error) {
+    return (
+      <div className="rounded-lg border border-red-500/30 bg-red-500/10 p-4">
+        <p className="text-sm text-red-400">{error}</p>
+        <button
+          type="button"
+          onClick={() => void loadHealth()}
+          className="mt-2 text-xs text-red-300 underline hover:no-underline"
+        >
+          Retry
+        </button>
+      </div>
+    );
+  }
+
+  if (!health) return <></>;
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <StatusBadge status={health.status} />
+          <span className="text-sm text-text-muted">
+            Last checked: {new Date(health.checkedAt).toLocaleTimeString()}
+          </span>
+        </div>
+        <button
+          type="button"
+          onClick={() => void loadHealth()}
+          className="text-xs text-blue-400 hover:text-blue-300"
+        >
+          Refresh
+        </button>
+      </div>
+
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+        {/* Database */}
+        <HealthCard title="Database (PostgreSQL)" status={health.database.status}>
+          {health.database.latencyMs !== undefined && (
+            <p className="text-xs text-text-muted">Latency: {health.database.latencyMs}ms</p>
+          )}
+          {health.database.error && <p className="text-xs text-red-400">{health.database.error}</p>}
+        </HealthCard>
+
+        {/* Cache */}
+        <HealthCard title="Cache (Valkey)" status={health.cache.status}>
+          {health.cache.latencyMs !== undefined && (
+            <p className="text-xs text-text-muted">Latency: {health.cache.latencyMs}ms</p>
+          )}
+          {health.cache.error && <p className="text-xs text-red-400">{health.cache.error}</p>}
+        </HealthCard>
+
+        {/* Agent Pool */}
+        <HealthCard title="Agent Pool" status="ok">
+          <p className="text-xs text-text-muted">
+            Active sessions: {health.agentPool.activeSessions}
+          </p>
+        </HealthCard>
+
+        {/* Providers */}
+        <HealthCard
+          title="LLM Providers"
+          status={health.providers.some((p) => p.available) ? 'ok' : 'error'}
+        >
+          {health.providers.length === 0 ? (
+            <p className="text-xs text-text-muted">No providers configured</p>
+          ) : (
+            <ul className="space-y-1">
+              {health.providers.map((p) => (
+                <li key={p.id} className="flex items-center justify-between text-xs">
+                  <span className="text-text-secondary">{p.name}</span>
+                  <span
+                    className={cn(
+                      'rounded-full px-1.5 py-0.5',
+                      p.available ? 'bg-green-500/20 text-green-400' : 'bg-red-500/20 text-red-400',
+                    )}
+                  >
+                    {p.available ? `${p.modelCount} models` : 'unavailable'}
+                  </span>
+                </li>
+              ))}
+            </ul>
+          )}
+        </HealthCard>
+      </div>
+    </div>
+  );
+}
+
+// ── Helper Components ─────────────────────────────────────────────────────────
+
+function StatusBadge({ status }: { status: 'ok' | 'degraded' | 'error' }): React.ReactElement {
+  const map = {
+    ok: 'bg-green-500/20 text-green-400',
+    degraded: 'bg-yellow-500/20 text-yellow-400',
+    error: 'bg-red-500/20 text-red-400',
+  };
+  return (
+    <span className={cn('rounded-full px-2 py-0.5 text-xs font-medium capitalize', map[status])}>
+      {status}
+    </span>
+  );
+}
+
+interface HealthCardProps {
+  title: string;
+  status: 'ok' | 'error';
+  children?: React.ReactNode;
+}
+
+function HealthCard({ title, status, children }: HealthCardProps): React.ReactElement {
+  return (
+    <div className="rounded-lg border border-surface-border bg-surface-card p-4">
+      <div className="mb-2 flex items-center justify-between">
+        <h3 className="text-sm font-medium text-text-primary">{title}</h3>
+        <span
+          className={cn('h-2 w-2 rounded-full', status === 'ok' ? 'bg-green-400' : 'bg-red-400')}
+        />
+      </div>
+      {children}
+    </div>
+  );
+}

apps/web/src/spa/pages/settings.spec.tsx

@@ -0,0 +1,178 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { createMemoryRouter, RouterProvider, type RouteObject } from 'react-router-dom';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+const { apiMock, useSessionMock, updateUserMock } = vi.hoisted(() => ({
+  apiMock: vi.fn(),
+  useSessionMock: vi.fn(),
+  updateUserMock: vi.fn(),
+}));
+
+vi.mock('@/lib/api', () => ({
+  api: apiMock,
+}));
+
+vi.mock('@/lib/auth-client', () => ({
+  useSession: useSessionMock,
+  authClient: { updateUser: updateUserMock },
+}));
+
+import { SettingsPage } from './settings';
+
+let root: Root | null = null;
+let container: HTMLDivElement;
+
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
+    configurable: true,
+    value: true,
+  });
+});
+
+afterAll(() => {
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+});
+
+afterEach(async () => {
+  await act(async () => {
+    root?.unmount();
+  });
+  document.body.replaceChildren();
+  root = null;
+  apiMock.mockReset();
+  useSessionMock.mockReset();
+  updateUserMock.mockReset();
+});
+
+async function renderSettingsPage(): Promise<void> {
+  const routes: RouteObject[] = [{ path: '/settings', element: <SettingsPage /> }];
+  const router = createMemoryRouter(routes, { initialEntries: ['/settings'] });
+  container = document.createElement('div');
+  document.body.append(container);
+  root = createRoot(container);
+
+  await act(async () => {
+    root?.render(<RouterProvider router={router} />);
+  });
+}
+
+function clickButtonByText(text: string): Promise<void> {
+  const button = [...container.querySelectorAll('button')].find((candidate) =>
+    candidate.textContent?.includes(text),
+  );
+  if (!button) {
+    throw new Error(`Button containing "${text}" not found`);
+  }
+  return act(async () => {
+    button.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+  });
+}
+
+const session = {
+  user: { id: 'u-1', name: 'Test User', email: '[email protected]', image: null },
+};
+
+describe('SettingsPage profile tab', () => {
+  it('renders the profile form from the session and saves via authClient', async () => {
+    useSessionMock.mockReturnValue({ data: session, isPending: false });
+    updateUserMock.mockResolvedValue({});
+
+    await renderSettingsPage();
+
+    const nameInput = container.querySelector<HTMLInputElement>('#profile-name');
+    const emailInput = container.querySelector<HTMLInputElement>('#profile-email');
+    expect(nameInput?.value).toBe('Test User');
+    expect(emailInput?.value).toBe('[email protected]');
+    expect(emailInput?.disabled).toBe(true);
+
+    await clickButtonByText('Save changes');
+
+    expect(updateUserMock).toHaveBeenCalledWith({ name: 'Test User', image: null });
+    expect(container.textContent).toContain('Saved!');
+  });
+
+  it('surfaces an update failure without clearing the form', async () => {
+    useSessionMock.mockReturnValue({ data: session, isPending: false });
+    updateUserMock.mockResolvedValue({ error: { message: 'name rejected' } });
+
+    await renderSettingsPage();
+    await clickButtonByText('Save changes');
+
+    expect(container.textContent).toContain('name rejected');
+    expect(container.querySelector<HTMLInputElement>('#profile-name')?.value).toBe('Test User');
+  });
+});
+
+describe('SettingsPage appearance tab', () => {
+  it('loads preferences and posts each changed preference on save', async () => {
+    useSessionMock.mockReturnValue({ data: session, isPending: false });
+    apiMock.mockImplementation((path: string) =>
+      path.startsWith('/api/memory/preferences?')
+        ? Promise.resolve([{ key: 'ui.theme', value: 'dark', category: 'appearance' }])
+        : Promise.resolve({}),
+    );
+
+    await renderSettingsPage();
+    await clickButtonByText('Appearance');
+
+    expect(apiMock).toHaveBeenCalledWith('/api/memory/preferences?category=appearance');
+
+    await clickButtonByText('Save changes');
+
+    expect(apiMock).toHaveBeenCalledWith('/api/memory/preferences', {
+      method: 'POST',
+      body: { key: 'ui.theme', value: 'dark', category: 'appearance', source: 'user' },
+    });
+  });
+});
+
+describe('SettingsPage providers tab', () => {
+  it('loads LLM and SSO providers and runs a connection test', async () => {
+    useSessionMock.mockReturnValue({ data: session, isPending: false });
+    apiMock.mockImplementation((path: string, opts?: { method?: string }) => {
+      if (path === '/api/providers' && opts === undefined) {
+        return Promise.resolve([
+          {
+            id: 'ollama',
+            name: 'Ollama',
+            available: true,
+            models: [
+              {
+                id: 'llama3.2',
+                provider: 'ollama',
+                name: 'Llama 3.2',
+                reasoning: false,
+                contextWindow: 128_000,
+                maxTokens: 4096,
+                inputTypes: ['text'],
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+              },
+            ],
+          },
+        ]);
+      }
+      if (path === '/api/sso/providers') {
+        return Promise.resolve([]);
+      }
+      if (path === '/api/providers/test') {
+        return Promise.resolve({ providerId: 'ollama', reachable: true, latencyMs: 12 });
+      }
+      return Promise.resolve([]);
+    });
+
+    await renderSettingsPage();
+    await clickButtonByText('Providers');
+
+    expect(container.textContent).toContain('Ollama');
+    expect(container.textContent).toContain('1 model');
+
+    await clickButtonByText('Test');
+
+    expect(apiMock).toHaveBeenCalledWith('/api/providers/test', {
+      method: 'POST',
+      body: { providerId: 'ollama' },
+    });
+    expect(container.textContent).toContain('Reachable');
+  });
+});

apps/web/src/spa/pages/settings.tsx

@@ -0,0 +1,826 @@
+import { useCallback, useEffect, useState } from 'react';
+import { api } from '@/lib/api';
+import { authClient, useSession } from '@/lib/auth-client';
+import type { SsoProviderDiscovery } from '@/lib/sso';
+import { SsoProviderSection } from '@/components/settings/sso-provider-section';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+interface ModelInfo {
+  id: string;
+  provider: string;
+  name: string;
+  reasoning: boolean;
+  contextWindow: number;
+  maxTokens: number;
+  inputTypes: ('text' | 'image')[];
+  cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+}
+
+interface ProviderInfo {
+  id: string;
+  name: string;
+  available: boolean;
+  models: ModelInfo[];
+}
+
+interface TestConnectionResult {
+  providerId: string;
+  reachable: boolean;
+  latencyMs?: number;
+  error?: string;
+  discoveredModels?: string[];
+}
+
+type TestState = 'idle' | 'testing' | 'success' | 'error';
+
+interface ProviderTestStatus {
+  state: TestState;
+  result?: TestConnectionResult;
+}
+
+interface Preference {
+  key: string;
+  value: unknown;
+  category: string;
+}
+
+type Theme = 'light' | 'dark' | 'system';
+type SaveState = 'idle' | 'saving' | 'saved' | 'error';
+type Tab = 'profile' | 'appearance' | 'notifications' | 'providers';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function prefValue<T>(prefs: Preference[], key: string, fallback: T): T {
+  const p = prefs.find((x) => x.key === key);
+  if (p === undefined) return fallback;
+  return p.value as T;
+}
+
+// ─── Main Page ────────────────────────────────────────────────────────────────
+
+export function SettingsPage(): React.ReactElement {
+  const { data: session } = useSession();
+  const [activeTab, setActiveTab] = useState<Tab>('profile');
+
+  const tabs: { id: Tab; label: string }[] = [
+    { id: 'profile', label: 'Profile' },
+    { id: 'appearance', label: 'Appearance' },
+    { id: 'notifications', label: 'Notifications' },
+    { id: 'providers', label: 'Providers' },
+  ];
+
+  return (
+    <div className="mx-auto max-w-3xl space-y-6">
+      <h1 className="text-2xl font-semibold">Settings</h1>
+
+      {/* Tab bar */}
+      <div className="flex gap-1 border-b border-surface-border">
+        {tabs.map((tab) => (
+          <button
+            key={tab.id}
+            type="button"
+            onClick={() => setActiveTab(tab.id)}
+            className={`px-4 py-2 text-sm font-medium transition-colors ${
+              activeTab === tab.id
+                ? 'border-b-2 border-accent text-accent'
+                : 'text-text-secondary hover:text-text-primary'
+            }`}
+          >
+            {tab.label}
+          </button>
+        ))}
+      </div>
+
+      {activeTab === 'profile' && <ProfileTab session={session} />}
+      {activeTab === 'appearance' && <AppearanceTab />}
+      {activeTab === 'notifications' && <NotificationsTab />}
+      {activeTab === 'providers' && <ProvidersTab />}
+    </div>
+  );
+}
+
+// ─── Profile Tab ──────────────────────────────────────────────────────────────
+
+function ProfileTab({
+  session,
+}: {
+  session: { user: { id: string; name: string; email: string; image?: string | null } } | null;
+}): React.ReactElement {
+  const [name, setName] = useState(session?.user.name ?? '');
+  const [image, setImage] = useState(session?.user.image ?? '');
+  const [saveState, setSaveState] = useState<SaveState>('idle');
+  const [errorMsg, setErrorMsg] = useState('');
+
+  // Sync from session when it loads
+  useEffect(() => {
+    if (session?.user) {
+      setName(session.user.name ?? '');
+      setImage(session.user.image ?? '');
+    }
+  }, [session]);
+
+  const handleSave = async (): Promise<void> => {
+    setSaveState('saving');
+    setErrorMsg('');
+    try {
+      const result = await authClient.updateUser({ name, image: image || null });
+      if (result.error) {
+        setErrorMsg(result.error.message ?? 'Failed to update profile');
+        setSaveState('error');
+        return;
+      }
+      setSaveState('saved');
+      setTimeout(() => setSaveState('idle'), 2000);
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Failed to update profile';
+      setErrorMsg(message);
+      setSaveState('error');
+    }
+  };
+
+  return (
+    <section className="space-y-4">
+      <h2 className="text-lg font-medium text-text-secondary">Profile</h2>
+      <div className="rounded-lg border border-surface-border bg-surface-card p-6 space-y-4">
+        <FormField label="Display Name" id="profile-name">
+          <input
+            id="profile-name"
+            type="text"
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+            placeholder="Your name"
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-accent focus:outline-none focus:ring-1 focus:ring-accent"
+          />
+        </FormField>
+
+        <FormField label="Email" id="profile-email">
+          <input
+            id="profile-email"
+            type="email"
+            value={session?.user.email ?? ''}
+            disabled
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-muted opacity-60 cursor-not-allowed"
+          />
+          <p className="mt-1 text-xs text-text-muted">Email cannot be changed here.</p>
+        </FormField>
+
+        <FormField label="Avatar URL" id="profile-image">
+          <input
+            id="profile-image"
+            type="url"
+            value={image}
+            onChange={(e) => setImage(e.target.value)}
+            placeholder="https://example.com/avatar.png"
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-accent focus:outline-none focus:ring-1 focus:ring-accent"
+          />
+        </FormField>
+
+        <div className="flex items-center gap-3 pt-2">
+          <SaveButton state={saveState} onClick={handleSave} />
+          {saveState === 'error' && errorMsg && <p className="text-sm text-error">{errorMsg}</p>}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+// ─── Appearance Tab ───────────────────────────────────────────────────────────
+
+function AppearanceTab(): React.ReactElement {
+  const [loading, setLoading] = useState(true);
+  const [theme, setTheme] = useState<Theme>('system');
+  const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
+  const [defaultModel, setDefaultModel] = useState('');
+  const [saveState, setSaveState] = useState<SaveState>('idle');
+  const [errorMsg, setErrorMsg] = useState('');
+
+  useEffect(() => {
+    api<Preference[]>('/api/memory/preferences?category=appearance')
+      .catch(() => [] as Preference[])
+      .then((p) => {
+        setTheme(prefValue<Theme>(p, 'ui.theme', 'system'));
+        setSidebarCollapsed(prefValue<boolean>(p, 'ui.sidebar_collapsed', false));
+        setDefaultModel(prefValue<string>(p, 'ui.default_model', ''));
+      })
+      .finally(() => setLoading(false));
+  }, []);
+
+  const handleSave = async (): Promise<void> => {
+    setSaveState('saving');
+    setErrorMsg('');
+    try {
+      await Promise.all([
+        api('/api/memory/preferences', {
+          method: 'POST',
+          body: { key: 'ui.theme', value: theme, category: 'appearance', source: 'user' },
+        }),
+        api('/api/memory/preferences', {
+          method: 'POST',
+          body: {
+            key: 'ui.sidebar_collapsed',
+            value: sidebarCollapsed,
+            category: 'appearance',
+            source: 'user',
+          },
+        }),
+        ...(defaultModel
+          ? [
+              api('/api/memory/preferences', {
+                method: 'POST',
+                body: {
+                  key: 'ui.default_model',
+                  value: defaultModel,
+                  category: 'appearance',
+                  source: 'user',
+                },
+              }),
+            ]
+          : []),
+      ]);
+      setSaveState('saved');
+      setTimeout(() => setSaveState('idle'), 2000);
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Failed to save preferences';
+      setErrorMsg(message);
+      setSaveState('error');
+    }
+  };
+
+  if (loading) {
+    return (
+      <section>
+        <h2 className="mb-4 text-lg font-medium text-text-secondary">Appearance</h2>
+        <p className="text-sm text-text-muted">Loading preferences...</p>
+      </section>
+    );
+  }
+
+  return (
+    <section className="space-y-4">
+      <h2 className="text-lg font-medium text-text-secondary">Appearance</h2>
+      <div className="rounded-lg border border-surface-border bg-surface-card p-6 space-y-6">
+        {/* Theme */}
+        <div>
+          <label className="block text-sm font-medium text-text-primary mb-2">Theme</label>
+          <div className="flex gap-3">
+            {(['system', 'light', 'dark'] as Theme[]).map((t) => (
+              <button
+                key={t}
+                type="button"
+                onClick={() => setTheme(t)}
+                className={`rounded-lg border px-4 py-2 text-sm capitalize transition-colors ${
+                  theme === t
+                    ? 'border-accent bg-accent/10 text-accent'
+                    : 'border-surface-border bg-surface-elevated text-text-secondary hover:border-accent/50'
+                }`}
+              >
+                {t}
+              </button>
+            ))}
+          </div>
+        </div>
+
+        {/* Sidebar collapsed default */}
+        <div className="flex items-center justify-between">
+          <div>
+            <p className="text-sm font-medium text-text-primary">Collapse sidebar by default</p>
+            <p className="text-xs text-text-muted">Start with sidebar collapsed on page load</p>
+          </div>
+          <Toggle checked={sidebarCollapsed} onChange={setSidebarCollapsed} />
+        </div>
+
+        {/* Default model */}
+        <FormField label="Default Model" id="default-model">
+          <input
+            id="default-model"
+            type="text"
+            value={defaultModel}
+            onChange={(e) => setDefaultModel(e.target.value)}
+            placeholder="e.g. ollama/llama3.2"
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-accent focus:outline-none focus:ring-1 focus:ring-accent"
+          />
+          <p className="mt-1 text-xs text-text-muted">
+            Model ID to pre-select for new conversations.
+          </p>
+        </FormField>
+
+        <div className="flex items-center gap-3 pt-2">
+          <SaveButton state={saveState} onClick={handleSave} />
+          {saveState === 'error' && errorMsg && <p className="text-sm text-error">{errorMsg}</p>}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+// ─── Notifications Tab ────────────────────────────────────────────────────────
+
+function NotificationsTab(): React.ReactElement {
+  const [loading, setLoading] = useState(true);
+  const [emailAgentComplete, setEmailAgentComplete] = useState(false);
+  const [emailMentions, setEmailMentions] = useState(true);
+  const [emailDigest, setEmailDigest] = useState(false);
+  const [saveState, setSaveState] = useState<SaveState>('idle');
+  const [errorMsg, setErrorMsg] = useState('');
+
+  useEffect(() => {
+    api<Preference[]>('/api/memory/preferences?category=communication')
+      .catch(() => [] as Preference[])
+      .then((p) => {
+        setEmailAgentComplete(prefValue<boolean>(p, 'notify.email_agent_complete', false));
+        setEmailMentions(prefValue<boolean>(p, 'notify.email_mentions', true));
+        setEmailDigest(prefValue<boolean>(p, 'notify.email_digest', false));
+      })
+      .finally(() => setLoading(false));
+  }, []);
+
+  const handleSave = async (): Promise<void> => {
+    setSaveState('saving');
+    setErrorMsg('');
+    try {
+      await Promise.all([
+        api('/api/memory/preferences', {
+          method: 'POST',
+          body: {
+            key: 'notify.email_agent_complete',
+            value: emailAgentComplete,
+            category: 'communication',
+            source: 'user',
+          },
+        }),
+        api('/api/memory/preferences', {
+          method: 'POST',
+          body: {
+            key: 'notify.email_mentions',
+            value: emailMentions,
+            category: 'communication',
+            source: 'user',
+          },
+        }),
+        api('/api/memory/preferences', {
+          method: 'POST',
+          body: {
+            key: 'notify.email_digest',
+            value: emailDigest,
+            category: 'communication',
+            source: 'user',
+          },
+        }),
+      ]);
+      setSaveState('saved');
+      setTimeout(() => setSaveState('idle'), 2000);
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Failed to save preferences';
+      setErrorMsg(message);
+      setSaveState('error');
+    }
+  };
+
+  if (loading) {
+    return (
+      <section>
+        <h2 className="mb-4 text-lg font-medium text-text-secondary">Notifications</h2>
+        <p className="text-sm text-text-muted">Loading preferences...</p>
+      </section>
+    );
+  }
+
+  return (
+    <section className="space-y-4">
+      <h2 className="text-lg font-medium text-text-secondary">Notifications</h2>
+      <div className="rounded-lg border border-surface-border bg-surface-card p-6 space-y-6">
+        <p className="text-xs text-text-muted">Configure when you receive email notifications.</p>
+
+        <NotifyRow
+          label="Agent task completed"
+          description="Email when an agent finishes a task"
+          checked={emailAgentComplete}
+          onChange={setEmailAgentComplete}
+        />
+        <NotifyRow
+          label="Mentions"
+          description="Email when you are mentioned in a conversation"
+          checked={emailMentions}
+          onChange={setEmailMentions}
+        />
+        <NotifyRow
+          label="Weekly digest"
+          description="Weekly summary of activity"
+          checked={emailDigest}
+          onChange={setEmailDigest}
+        />
+
+        <div className="flex items-center gap-3 pt-2">
+          <SaveButton state={saveState} onClick={handleSave} />
+          {saveState === 'error' && errorMsg && <p className="text-sm text-error">{errorMsg}</p>}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+// ─── Providers Tab ────────────────────────────────────────────────────────────
+
+function ProvidersTab(): React.ReactElement {
+  const [providers, setProviders] = useState<ProviderInfo[]>([]);
+  const [ssoProviders, setSsoProviders] = useState<SsoProviderDiscovery[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [ssoLoading, setSsoLoading] = useState(true);
+  const [testStatuses, setTestStatuses] = useState<Record<string, ProviderTestStatus>>({});
+
+  useEffect(() => {
+    api<ProviderInfo[]>('/api/providers')
+      .catch(() => [] as ProviderInfo[])
+      .then((p) => setProviders(p))
+      .finally(() => setLoading(false));
+  }, []);
+
+  useEffect(() => {
+    api<SsoProviderDiscovery[]>('/api/sso/providers')
+      .catch(() => [] as SsoProviderDiscovery[])
+      .then((providers) => setSsoProviders(providers))
+      .finally(() => setSsoLoading(false));
+  }, []);
+
+  const testConnection = useCallback(async (providerId: string): Promise<void> => {
+    setTestStatuses((prev) => ({
+      ...prev,
+      [providerId]: { state: 'testing' },
+    }));
+    try {
+      const result = await api<TestConnectionResult>('/api/providers/test', {
+        method: 'POST',
+        body: { providerId },
+      });
+      setTestStatuses((prev) => ({
+        ...prev,
+        [providerId]: { state: result.reachable ? 'success' : 'error', result },
+      }));
+    } catch {
+      setTestStatuses((prev) => ({
+        ...prev,
+        [providerId]: {
+          state: 'error',
+          result: { providerId, reachable: false, error: 'Request failed' },
+        },
+      }));
+    }
+  }, []);
+
+  const defaultModel: ModelInfo | undefined = providers
+    .flatMap((p) => p.models)
+    .find((m) => providers.find((p) => p.id === m.provider)?.available);
+
+  return (
+    <section className="space-y-6">
+      <div className="space-y-4">
+        <h2 className="text-lg font-medium text-text-secondary">SSO Providers</h2>
+        <SsoProviderSection providers={ssoProviders} loading={ssoLoading} />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-lg font-medium text-text-secondary">LLM Providers</h2>
+        {loading ? (
+          <p className="text-sm text-text-muted">Loading providers...</p>
+        ) : providers.length === 0 ? (
+          <div className="rounded-lg border border-surface-border bg-surface-card p-4">
+            <p className="text-sm text-text-muted">
+              No providers configured. Set{' '}
+              <code className="rounded bg-surface-elevated px-1 py-0.5 text-xs">
+                OLLAMA_BASE_URL
+              </code>{' '}
+              or{' '}
+              <code className="rounded bg-surface-elevated px-1 py-0.5 text-xs">
+                MOSAIC_CUSTOM_PROVIDERS
+              </code>{' '}
+              to add providers.
+            </p>
+          </div>
+        ) : (
+          <div className="space-y-4">
+            {providers.map((provider) => (
+              <ProviderCard
+                key={provider.id}
+                provider={provider}
+                defaultModel={defaultModel}
+                testStatus={testStatuses[provider.id] ?? { state: 'idle' }}
+                onTest={() => void testConnection(provider.id)}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+    </section>
+  );
+}
+
+// ─── Shared UI Components ─────────────────────────────────────────────────────
+
+function FormField({
+  label,
+  id,
+  children,
+}: {
+  label: string;
+  id: string;
+  children: React.ReactNode;
+}): React.ReactElement {
+  return (
+    <div>
+      <label htmlFor={id} className="block text-sm font-medium text-text-primary">
+        {label}
+      </label>
+      {children}
+    </div>
+  );
+}
+
+function Toggle({
+  checked,
+  onChange,
+}: {
+  checked: boolean;
+  onChange: (v: boolean) => void;
+}): React.ReactElement {
+  return (
+    <button
+      type="button"
+      role="switch"
+      aria-checked={checked}
+      onClick={() => onChange(!checked)}
+      className={`relative inline-flex h-6 w-11 items-center rounded-full transition-colors focus:outline-none focus:ring-2 focus:ring-accent focus:ring-offset-2 focus:ring-offset-surface-card ${
+        checked ? 'bg-accent' : 'bg-surface-border'
+      }`}
+    >
+      <span
+        className={`inline-block h-4 w-4 transform rounded-full bg-white transition-transform ${
+          checked ? 'translate-x-6' : 'translate-x-1'
+        }`}
+      />
+    </button>
+  );
+}
+
+function NotifyRow({
+  label,
+  description,
+  checked,
+  onChange,
+}: {
+  label: string;
+  description: string;
+  checked: boolean;
+  onChange: (v: boolean) => void;
+}): React.ReactElement {
+  return (
+    <div className="flex items-center justify-between">
+      <div>
+        <p className="text-sm font-medium text-text-primary">{label}</p>
+        <p className="text-xs text-text-muted">{description}</p>
+      </div>
+      <Toggle checked={checked} onChange={onChange} />
+    </div>
+  );
+}
+
+function SaveButton({
+  state,
+  onClick,
+}: {
+  state: SaveState;
+  onClick: () => void;
+}): React.ReactElement {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={state === 'saving'}
+      className="rounded-lg bg-accent px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-accent/90 disabled:cursor-not-allowed disabled:opacity-50"
+    >
+      {state === 'saving' ? 'Saving...' : state === 'saved' ? 'Saved!' : 'Save changes'}
+    </button>
+  );
+}
+
+// ─── Provider Card (from original page) ──────────────────────────────────────
+
+interface ProviderCardProps {
+  provider: ProviderInfo;
+  defaultModel: ModelInfo | undefined;
+  testStatus: ProviderTestStatus;
+  onTest: () => void;
+}
+
+function ProviderCard({
+  provider,
+  defaultModel,
+  testStatus,
+  onTest,
+}: ProviderCardProps): React.ReactElement {
+  const [expanded, setExpanded] = useState(false);
+
+  return (
+    <div className="rounded-lg border border-surface-border bg-surface-card">
+      {/* Header row */}
+      <div className="flex items-center justify-between px-4 py-3">
+        <div className="flex items-center gap-3">
+          <ProviderAvatar id={provider.id} />
+          <div>
+            <div className="flex items-center gap-2">
+              <span className="text-sm font-medium text-text-primary">{provider.name}</span>
+              <ProviderStatusBadge available={provider.available} />
+            </div>
+            <p className="text-xs text-text-muted">
+              {provider.models.length} model{provider.models.length !== 1 ? 's' : ''}
+            </p>
+          </div>
+        </div>
+
+        <div className="flex items-center gap-2">
+          <TestConnectionButton status={testStatus} onTest={onTest} />
+          <button
+            type="button"
+            onClick={() => setExpanded((v) => !v)}
+            className="rounded px-2 py-1 text-xs text-text-muted transition-colors hover:bg-surface-elevated hover:text-text-primary"
+            aria-expanded={expanded}
+            aria-label={expanded ? 'Collapse models' : 'Expand models'}
+          >
+            {expanded ? '▲ Hide' : '▼ Models'}
+          </button>
+        </div>
+      </div>
+
+      {/* Test result banner */}
+      {testStatus.state !== 'idle' && testStatus.state !== 'testing' && testStatus.result && (
+        <TestResultBanner result={testStatus.result} />
+      )}
+
+      {/* Model list */}
+      {expanded && (
+        <div className="border-t border-surface-border">
+          <table className="w-full">
+            <thead>
+              <tr className="bg-surface-elevated text-left text-xs text-text-muted">
+                <th className="px-4 py-2 font-medium">Model</th>
+                <th className="hidden px-4 py-2 font-medium md:table-cell">Capabilities</th>
+                <th className="hidden px-4 py-2 font-medium md:table-cell">Context</th>
+                <th className="hidden px-4 py-2 font-medium md:table-cell">Cost (in/out)</th>
+                <th className="px-4 py-2 font-medium">Default</th>
+              </tr>
+            </thead>
+            <tbody>
+              {provider.models.map((model) => (
+                <ModelRow
+                  key={model.id}
+                  model={model}
+                  isDefault={
+                    defaultModel?.id === model.id && defaultModel?.provider === model.provider
+                  }
+                />
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  );
+}
+
+interface ModelRowProps {
+  model: ModelInfo;
+  isDefault: boolean;
+}
+
+function ModelRow({ model, isDefault }: ModelRowProps): React.ReactElement {
+  return (
+    <tr className="border-t border-surface-border">
+      <td className="px-4 py-2">
+        <span className="text-sm text-text-primary">{model.name}</span>
+      </td>
+      <td className="hidden px-4 py-2 md:table-cell">
+        <div className="flex flex-wrap gap-1">
+          <CapabilityBadge label="chat" />
+          {model.reasoning && <CapabilityBadge label="reasoning" color="purple" />}
+          {model.inputTypes.includes('image') && <CapabilityBadge label="vision" color="blue" />}
+        </div>
+      </td>
+      <td className="hidden px-4 py-2 text-xs text-text-muted md:table-cell">
+        {formatContext(model.contextWindow)}
+      </td>
+      <td className="hidden px-4 py-2 text-xs text-text-muted md:table-cell">
+        {model.cost.input === 0 && model.cost.output === 0
+          ? 'free'
+          : `$${model.cost.input} / $${model.cost.output}`}
+      </td>
+      <td className="px-4 py-2 text-center">
+        {isDefault && (
+          <span
+            className="inline-block rounded-full bg-accent/20 px-2 py-0.5 text-xs font-medium text-accent"
+            title="Default model used for new sessions"
+          >
+            default
+          </span>
+        )}
+      </td>
+    </tr>
+  );
+}
+
+function ProviderAvatar({ id }: { id: string }): React.ReactElement {
+  const letter = id.charAt(0).toUpperCase();
+  return (
+    <div className="flex h-8 w-8 items-center justify-center rounded-full bg-surface-elevated text-sm font-semibold text-text-secondary">
+      {letter}
+    </div>
+  );
+}
+
+function ProviderStatusBadge({ available }: { available: boolean }): React.ReactElement {
+  return (
+    <span
+      className={`rounded-full px-2 py-0.5 text-xs font-medium ${
+        available ? 'bg-success/20 text-success' : 'bg-surface-elevated text-text-muted'
+      }`}
+    >
+      {available ? 'Active' : 'Inactive'}
+    </span>
+  );
+}
+
+interface TestConnectionButtonProps {
+  status: ProviderTestStatus;
+  onTest: () => void;
+}
+
+function TestConnectionButton({ status, onTest }: TestConnectionButtonProps): React.ReactElement {
+  const isTesting = status.state === 'testing';
+  return (
+    <button
+      type="button"
+      onClick={onTest}
+      disabled={isTesting}
+      className="rounded px-2 py-1 text-xs transition-colors hover:bg-surface-elevated disabled:cursor-not-allowed disabled:opacity-50"
+      title="Test connection"
+    >
+      {isTesting ? (
+        <span className="text-text-muted">Testing…</span>
+      ) : status.state === 'success' ? (
+        <span className="text-success">✓ Reachable</span>
+      ) : status.state === 'error' ? (
+        <span className="text-error">✗ Unreachable</span>
+      ) : (
+        <span className="text-text-muted">Test</span>
+      )}
+    </button>
+  );
+}
+
+function TestResultBanner({ result }: { result: TestConnectionResult }): React.ReactElement {
+  return (
+    <div
+      className={`px-4 py-2 text-xs ${
+        result.reachable ? 'bg-success/10 text-success' : 'bg-error/10 text-error'
+      }`}
+    >
+      {result.reachable ? (
+        <>
+          Connected
+          {result.latencyMs !== undefined && (
+            <span className="ml-1 opacity-70">({result.latencyMs}ms)</span>
+          )}
+          {result.discoveredModels && result.discoveredModels.length > 0 && (
+            <span className="ml-2 opacity-70">
+              — {result.discoveredModels.length} model
+              {result.discoveredModels.length !== 1 ? 's' : ''} discovered
+            </span>
+          )}
+        </>
+      ) : (
+        <>Connection failed{result.error ? `: ${result.error}` : ''}</>
+      )}
+    </div>
+  );
+}
+
+function CapabilityBadge({
+  label,
+  color = 'default',
+}: {
+  label: string;
+  color?: 'default' | 'purple' | 'blue';
+}): React.ReactElement {
+  const colorClass =
+    color === 'purple'
+      ? 'bg-purple-500/20 text-purple-400'
+      : color === 'blue'
+        ? 'bg-blue-500/20 text-blue-400'
+        : 'bg-surface-elevated text-text-muted';
+  return <span className={`rounded px-1.5 py-0.5 text-xs ${colorClass}`}>{label}</span>;
+}
+
+function formatContext(tokens: number): string {
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`;
+  if (tokens >= 1_000) return `${Math.round(tokens / 1_000)}k`;
+  return String(tokens);
+}

docs/requirements/hierarchy-schema.md

@@ -1,380 +0,0 @@
-# Hierarchy Schema Contract (D2)
-
-Status: DRAFT — awaiting ratification (webui-audit S2, contract 1 of 9).
-Authority: PRD D2/D9/D13 (Part I §4) and the native-kanban SOT Amendment A1
-(`docs/requirements/native-kanban-sot.md` §8, ratified 2026-08-25). This
-document turns the ratified hierarchy into a concrete schema contract:
-tables, cardinalities, constraints, and ownership/transfer semantics. It is
-the prerequisite for the hierarchy command family and for the RBAC grant
-model (contract 2, `docs/requirements/rbac-grant-model.md`).
-
-Revision 2 (independent review, GPT-5.6 terra): tenancy-FK exemption made
-explicit (§1.1); record class extended to include `hierarchy_grants`
-(§1.1); provenance corrections on legacy tables and the planning `projects`
-table (§1.3, §2 naming note); NOT NULL and `NULLS NOT DISTINCT` grant
-uniqueness (§2.6, §3.2); grant FK delete actions split cascade/restrict
-(§3.3); transfer transaction includes its audit write (§4.3); ownership
-invariant completed via contract 2 with the both-sides rule marked as new
-policy (§4.2, §4.4); hierarchy audit brought under REQ-AUD-001-equivalent
-guarantees with deletion-safe linkage (§5.2); roll-up never-a-write restored
-to full A1 strength (§5.4); §6 rebuilt with bounded observables for every
-MUST (allowlist, command surface, audit, corrected cardinality witness).
-
-Revision 3 (terra re-review residuals): §4.3 transfer write inventory
-reconciled with §5.2 — the transaction's writes are the single class-row
-mutation plus that mutation's §5.2 audit writes (event + outbox record),
-not "exactly two writes"; §6.3 extended with a closed writer-coverage
-witness so an unregistered internal writer cannot pass a registered-route
-inventory. (Terra's finding-8 residual — a stale contract 2 §7.8 backlink
-to contract 1 §6.2 — was already fixed in contract 2 revision 2, which
-cites §6.5; measured against `origin/contract/rbac-grants` head
-`501112d2`.)
-
-Revision 4 (terra r3 residual F7): the §6.3(b) writer-coverage assertion
-extended to raw SQL — it now also fails on class-table name literals
-inside SQL strings or tagged SQL templates outside the allowlist, so a
-raw-SQL writer that touches no schema symbol is still caught.
-
-Revision 5 (terra r4 residual F7): §6.3(b) gains a third prong — any
-raw-SQL execution primitive outside the allowlist fails the assertion
-regardless of its SQL content, closing the evasion where a
-dynamically constructed table name carries neither a schema symbol nor
-a class-table literal. The detection claim is now coextensive with
-what the three prongs statically see.
-
-Revision 6 (terra r5 residual F7 + new F8): the "two prongs" wording
-corrected to three (F8); §6.3(b) gains the allowlist composition rules
-(no generic raw-SQL helper is allowlisted; an allowlisted module may
-not export caller-supplied-SQL execution) and fails outright on
-runtime code-construction primitives; the detection claim is scoped
-honestly to the stated syntactic forms, with evasions beyond static
-reach assigned to §5.1 review/audit rather than claimed for CI.
-
-Revision 7 (terra r6 new F9): the false-positive remedy no longer
-contradicts the composition rules — legitimate non-hierarchy raw
-execution (e.g. the db package's migration runner) is dispositioned
-onto a second closed enumerated list, the infrastructure register,
-exempt from prong (iii) only, still bound by prongs (i)/(ii), barred
-from the writer allowlist, and importable only by registered modules
-or the operational entry points.
-
-Revision 8 (terra r7 residual F9): the register's import rule made
-satisfiable by the live tree — imports are checked re-export-aware
-(package barrels followed), and each registered module carries its own
-closed importer enumeration, which may name operational entry points
-such as the Gateway's startup migration hook; named importers stay
-subject to prongs (i)/(ii) and gain no writer standing.
-
-Revision 9 (terra r8 F10): revision 8 called the Gateway database
-module the runner's "one live importer today". That was false — the
-measured production importer set has four members. The enumeration
-example now lists the complete measured set, and the import analysis
-is extended to resolve literal dynamic `import()` routes, which two of
-the four members use.
-
-Scope: the tenancy/authorization structure record class — companies,
-estates, platform-projects, workspaces, hierarchy grants, their parentage,
-and constraints. Out of scope: the RBAC grant vocabulary and evaluation
-semantics (contract 2), roll-up projection semantics (contract 8), kanban
-planning entities inside workspaces (SOT §5), migration or retirement of
-legacy flat data (future work; see §1.3).
-
-## 1. Record class and placement
-
-1. The **tenancy/authorization structure record class** defined by
-   Amendment A1 §8.1.2 comprises five tables: the four node tables of §2
-   AND `hierarchy_grants` (§3) — A1 includes hierarchy-level access grants
-   in the class. Every rule addressed to "the class" in this contract
-   (payload prohibition, mutation path, audit) binds all five tables. Class
-   rows carry parentage, naming, grant, and audit-linkage data only — never
-   task, plan, or any business/orchestration payload.
-   References from business/orchestration rows into the class are limited
-   to exactly one form: the canonical `workspace_id` tenancy column that
-   REQ-TEN-001 requires on every canonical row, referencing
-   `workspaces.id`. No business/orchestration row may reference a company,
-   estate, platform-project, or grant id in any position, and no
-   business/orchestration row may reference a workspace id in any
-   non-tenancy position (dependency, claim target, work subject).
-2. Hierarchy records are NOT workspace-scoped rows: REQ-TEN-001's
-   `workspace_id` obligation binds business/orchestration rows and does not
-   apply to this class (A1 §8.1.2). The `workspaces` table itself is the
-   anchor the obligation points at.
-3. The legacy flat tables (`teams`, and the Brain planning `projects` table
-   in `packages/db/src/schema.ts`) are not part of this class. What A1
-   §8.1.4 pins is narrower: the planning `projects` table and
-   `platform_projects` stay distinct tables. This contract adds, as new
-   policy ratified here: neither `teams` nor `projects` is repurposed as a
-   hierarchy table. Their eventual migration or retirement is future work
-   that no existing REQ assigns; it is out of scope here.
-
-## 2. Tables and cardinalities
-
-Naming: the level above workspaces is `platform_projects`, per A1 §8.1.4.
-The existing `projects` table is Brain planning data (so labeled in
-`packages/db/src/schema.ts`; it carries no `workspace_id`), and the schema
-MUST NOT merge the two. (A rename of either remains an implementation-PR
-decision under A1; this contract pins only that they stay distinct tables.)
-
-1. `companies` — id (uuid pk), name, slug (unique per deployment),
-   created_at, updated_at. N per deployment (D2).
-2. `estates` — id, name, slug, `company_id` NOT NULL →
-   `companies.id` ON DELETE RESTRICT. Exactly one company per estate; a
-   company holds any number of estates.
-3. `platform_projects` — id, name, slug, `estate_id` NOT NULL →
-   `estates.id` ON DELETE RESTRICT. Exactly one estate per
-   platform-project; an estate holds any number of platform-projects.
-4. `workspaces` — id, name, slug, `platform_project_id` NOT NULL →
-   `platform_projects.id` ON DELETE RESTRICT. Exactly one platform-project
-   per workspace. This table is the referent of every `workspace_id` column
-   the SOT requires on canonical rows.
-5. **Chain resolution is by construction.** Because every parent FK is NOT
-   NULL and single-valued (one FK column, no parentage edge tables, no
-   multi-parent forms, no nullable "detached" states), each workspace
-   resolves to exactly one platform-project → estate → company chain (A1
-   §8.3 acceptance 1). One-parent-per-child is the constrained direction;
-   many children per parent is valid data.
-6. **Slug scoping.** All `name` and `slug` columns are NOT NULL.
-   `estates.slug` is unique within its company, `platform_projects.slug`
-   within its estate, `workspaces.slug` within its platform-project
-   (composite unique constraints). Display names are unconstrained beyond
-   NOT NULL.
-7. No hierarchy table carries a `metadata` jsonb column or any
-   free-form payload field. The columns declared in this section and §3
-   are exhaustive: a class table's column set is exactly its declared set
-   (verified per §6.2) — nothing else (A1 §8.1.2).
-
-## 3. Grant attachment points
-
-The grant vocabulary (which roles exist, what each permits, how evaluation
-and revocation work) is contract 2. This contract pins only the schema
-shape contract 2 attaches to:
-
-1. `hierarchy_grants` — id, subject (exactly one of `user_id` → `users.id`,
-   `team_id` → `teams.id`; CHECK-enforced exactly-one-of), target (exactly
-   one of `company_id`, `estate_id`, `platform_project_id`;
-   CHECK-enforced exactly-one-of), `role` (text NOT NULL; vocabulary and
-   its CHECK constraint owned by contract 2 §2), `granted_by` NOT NULL →
-   `users.id`, created_at.
-2. Uniqueness: at most one grant row per (subject, target, role). Because
-   the subject and target columns are nullable by design, ordinary
-   PostgreSQL composite uniqueness treats NULLs as distinct and would not
-   enforce this. The implementation MUST use a single
-   `UNIQUE NULLS NOT DISTINCT` constraint across (`user_id`, `team_id`,
-   `company_id`, `estate_id`, `platform_project_id`, `role`) or six
-   equivalent partial unique indexes (one per subject×target form). The
-   pinned Drizzle ORM supports `nullsNotDistinct()`.
-3. Delete actions are split by column class:
-   - Target FKs (`company_id`, `estate_id`, `platform_project_id`):
-     ON DELETE CASCADE — the one permitted cascade in this class. A grant
-     on a deleted node is meaningless and fail-open if retained. Cascaded
-     grant deletions are audited per §5.2.
-   - Principal FKs (`user_id`, `team_id`, `granted_by`): ON DELETE
-     RESTRICT. The identity contract (§7.3) gates user deletion today and
-     defines no team-deletion rule; this contract does not invent one.
-     These FKs stay RESTRICT until an explicit deletion-and-retention
-     contract ratifies otherwise.
-4. Workspace-level access is evaluated, not stored here: a grant at any of
-   the three levels evaluates down the chain to workspace-scoped
-   authorization (A1 §8.1.3). No `workspace_id` column exists on
-   `hierarchy_grants` — workspace membership (REQ-ID-001) remains its own
-   mechanism inside the SOT schema, and the chain adds where grants can be
-   declared, never a bypass.
-
-## 4. Ownership and transfer
-
-"Assets are transferable subject to the structure" (PRD Part I §4):
-
-1. A transfer changes exactly one parent FK on exactly one hierarchy row:
-   workspace → new platform-project, platform-project → new estate, estate
-   → new company. Nothing else in the class or the SOT changes: business
-   and orchestration rows inside affected workspaces are untouched, keep
-   their `workspace_id`, and never cross a workspace boundary (A1 §8.1.3
-   "chain maintenance").
-2. Transfer authorization requires authority over BOTH the source and the
-   destination parent. This both-sides predicate is **new policy
-   introduced by this contract pair** (D2/A1 do not state it); its
-   evaluation semantics are contract 2 §5. The structural half — that the
-   transfer command evaluates it before mutating — binds here.
-3. A transfer transaction mutates exactly one class-table row — the
-   single-row parent-FK update — and contains, beyond that, only the
-   §5.2 audit writes for that mutation (the audit event and its
-   hierarchy-outbox record, committing in the same transaction). No other
-   class, business, or orchestration row changes. There are no multi-row
-   transfer batches at the schema level; bulk moves are N audited
-   transfers.
-4. Hierarchy records have no `owner_id`. Ownership in the hierarchy IS the
-   grant structure: a "company owner" is a subject with an `owner` grant
-   on that company or an ancestor (contract 2 §2), not a column. The
-   ownership invariant across the contract pair: a node may hold zero
-   direct owner grants (authority can derive from an ancestor grant); node
-   creation names the initial `owner` grant in the same audited operation
-   and the wizard seeds the first company's owner the same way (contract 2
-   §4.3); transfer and revocation semantics are contract 2 §§5–6. This
-   avoids column-encoded authority of the kind the legacy schema carries
-   (`teams.owner_id` and `teams.manager_id` are required user FKs, and
-   `team_members.role` is a further authority field — none of them
-   evaluable under a grant model).
-
-## 5. Mutation path, audit, and deletion
-
-1. All hierarchy mutations flow through the same sole-writable-SOT,
-   fail-closed, audited Gateway command path as everything else (A1 §8.2.3,
-   REQ-API-001). No direct-DB writers, no raw CRUD endpoints.
-2. **Audit parity.** A1 §8.2 leaves every pre-existing REQ binding, so
-   hierarchy mutations get REQ-AUD-001's guarantees, not a weakened
-   substitute. Concretely:
-   - Every create, rename, transfer, grant create/change/revoke, and
-     delete — including every grant deletion cascaded by a node delete —
-     emits a semantic audit event carrying actor, verb, target, and (for
-     transfers) source and destination parents, with the correlation,
-     causation, idempotency, and per-target ordering guarantees REQ-AUD-001
-     defines.
-   - The state change and its audit event(s) commit in the same
-     transaction, delivered through a transactional outbox. Hierarchy
-     events are not workspace-scoped rows and do not ride the workspace
-     outbox; they get an equivalent hierarchy outbox under the same
-     append-only, same-transaction rules.
-   - **Deletion-safe linkage:** audit events reference their target by an
-     immutable snapshot (id, slug, and parent chain at event time), never
-     by a foreign key into the class tables, so append-only events survive
-     the deletion of their target.
-3. Deletion is fail-closed bottom-up: a hierarchy record with children
-   cannot be deleted (RESTRICT FKs, §2). Deleting a workspace is a SOT-side
-   operation subject to the kanban SOT's own rules and is not granted any
-   new semantics by this contract.
-4. **Roll-up is never a write** (A1 §8.2.2, preserved at full strength). A
-   roll-up read mutates nothing — not hierarchy state, and not business or
-   orchestration state: it must not mutate, claim, order, or gate
-   workspace work. Contract 8 owns projection details but cannot narrow
-   this rule. This contract additionally guarantees the chain roll-ups
-   aggregate over is unique and non-null (§2.5).
-
-## 6. Verification requirements
-
-Binding on the implementing PRs (extends A1 §8.3):
-
-1. Schema witnesses (real PostgreSQL, §6.8): chain construction — insert
-   with a null parent FK refused; insert with one valid parent accepted;
-   two siblings under one parent accepted (the control proving the
-   constraint rejects only what §2.5 forbids); catalog assertion that each
-   child table has exactly one parent-FK column and no parentage edge
-   table exists. Composite slug uniqueness per parent (duplicate slug
-   under same parent refused; same slug under different parents accepted).
-   Grant CHECKs: exactly-one-of subject and exactly-one-of target each
-   witnessed (zero and two set → refused). Grant uniqueness: a duplicate
-   (subject, target, role) row refused for each of the six subject×target
-   forms, proving NULLS-NOT-DISTINCT semantics; NOT NULL on `role`,
-   `granted_by`, and all `name`/`slug` columns witnessed.
-2. Column allowlist: an information_schema assertion that each class
-   table's column set is exactly the set declared in §2/§3 — the bounded
-   observable for no-payload (§2.7) and no-`owner_id` (§4.4).
-3. Command surface: two witnesses, both required (§5.1). (a) Route
-   inventory: an assertion over the Gateway's registered hierarchy
-   routes/commands proving the registered mutation surface is exactly the
-   declared hierarchy command family — no generic CRUD endpoint. (b)
-   Writer coverage — the closed allowlist a route inventory cannot
-   provide: a static CI assertion over the Gateway and package sources
-   with three prongs, each bound to one explicitly enumerated allowlist
-   of hierarchy command/repository modules. (i) Symbol prong: write
-   references to the class-table schema symbols (insert, update, delete)
-   occur only in allowlisted modules. (ii) Literal prong: a class-table
-   name appearing inside a SQL string or tagged SQL template outside the
-   allowlist fails the assertion — this is what catches a raw-SQL writer
-   that references no schema symbol. (iii) Raw-execution prong: any call
-   to a raw-SQL execution primitive (the ORM's raw/unsafe constructors,
-   driver-level query/execute) outside the allowlist fails the
-   assertion, regardless of what the SQL string contains or how it is
-   constructed — the call site is statically detectable even when a
-   dynamically assembled table name is not, so a raw writer with a
-   runtime-built identifier is caught by its primitive, not its
-   payload. Two composition rules keep prong (iii) meaningful: the
-   allowlist names hierarchy command/repository modules only — a
-   generic raw-SQL helper or database-utility module is never
-   allowlisted; and an allowlisted module MUST NOT export a function
-   that executes caller-supplied SQL (such an export is itself a
-   raw-execution primitive, and the exporting module is treated as
-   unallowlisted for prong (iii) if it does). Legitimate raw execution
-   that is not a hierarchy writer — e.g. the migration runner in the
-   db package — lives on a second, separately enumerated
-   **infrastructure register**, distinct from the writer allowlist and
-   equally closed. A registered module is exempt from prong (iii) only:
-   prongs (i) and (ii) apply to it with no exemption, so it can hold no
-   class-table schema symbol or class-table SQL literal, and it can
-   never appear on the writer allowlist. To close the laundering path,
-   the same assertion checks imports, and the import analysis is
-   **re-export-aware**: it follows package barrels and re-exports, so a
-   route hidden behind an index module is still a route — and it
-   resolves literal dynamic imports the same way: an
-   `await import('<literal specifier>')` is an import edge like any
-   static import, not an evasion of the analysis (a dynamic import of
-   the db package whose specifier is not a literal fails the assertion
-   outright, because it makes the import graph unanalyzable). A
-   registered module may be imported only by other registered modules
-   or by importers named on that module's own closed importer
-   enumeration in the register — operational entry points such as the
-   migration/bootstrap CLI or the Gateway's startup migration hook.
-   The enumeration names the complete permitted production consumer
-   set, and completeness is measured, not asserted: the migration
-   runner's measured production importer set today has four members —
-   the Gateway database module (reached through the db package
-   barrel), the storage package's Postgres adapter, and two mosaic CLI
-   commands, the fleet-backlog command and the gateway verify command,
-   both routed through literal dynamic imports of the db package — so
-   its enumeration names those four. A module that only receives the
-   runner's functions by parameter injection (the gateway schema-check
-   module takes them as arguments from the verify command) has no
-   import edge of its own and is not enumerated. Any import route
-   outside the enumeration fails the assertion. Being a
-   named importer confers nothing else: the importer stays fully
-   subject to prongs (i) and (ii), gains no writer-allowlist standing,
-   and whether it uses the registered module beyond its operational
-   purpose is a §5.1 review question, not a static claim. Runtime code-construction
-   primitives (`eval`, `new Function`) anywhere in the scanned sources
-   fail the assertion outright, allowlist or not. Schema definitions
-   and generated migrations are excluded from the literal prong; a
-   false positive is resolved in the same PR by adding the module to
-   the one enumerated list its role permits — the writer allowlist for
-   a hierarchy command/repository module, the infrastructure register
-   for non-hierarchy raw execution — never by weakening the assertion,
-   and neither list may take a module the composition rules bar from
-   it. Both lists are closed, and the assertion's detection
-   claim is exactly its prongs: it statically surfaces every writer
-   expressed as a schema-symbol reference, a class-table SQL literal, a
-   raw-execution call site, or runtime code construction. An evasion
-   engineered outside those syntactic forms is a §5.1 violation that
-   review and audit own — the witness does not claim to catch what
-   static analysis cannot see, and any such evasion found later is
-   corrected as a conformance defect, not grandfathered.
-4. Audit witnesses: for each mutation class (create, rename, transfer,
-   grant create/change/revoke, delete) — the event exists after commit
-   with actor/verb/target and same-transaction atomicity; a rolled-back
-   mutation leaves no event (rollback witness); a node delete's cascaded
-   grant deletions are each covered by events; events survive deletion of
-   their target (query the events of a deleted node).
-5. Transfer tests: parent-FK update moves the subtree resolution and
-   modifies zero business/orchestration rows (row-count and content
-   assertions on workspace contents before/after); transfer without
-   authority on the source or on the destination side is refused (with
-   contract 2 §7.8).
-6. Deletion tests: delete with children refused at the database level;
-   delete of a leaf cascades its grants and nothing else; deleting a user
-   or team that is a grant subject (or `granted_by` referent) is refused
-   (RESTRICT witnesses for §3.3).
-7. Negative tests: no business/orchestration table accepts a company,
-   estate, platform-project, or grant id in any reference position, and
-   none accepts a workspace id in any non-tenancy position; the canonical
-   tenancy FK control — a business row inserted with a valid
-   `workspace_id` succeeds, with an invalid one is refused; roll-up
-   endpoints mutate no canonical state anywhere (assert zero writes across
-   hierarchy AND workspace tables, not hierarchy only); readers see
-   aggregates only over workspaces they are authorized on, with no
-   cross-tenant existence oracles (A1 §8.3 acceptance 3).
-8. Real-PostgreSQL coverage for every constraint witness (unique/CHECK/
-   RESTRICT/NULLS NOT DISTINCT behavior), using the `ci-postgres` service
-   in the `test` CI step; mocked specs cannot witness database constraints.
-
-## Ruling request
-
-Ratify sections 1–6 as written, with one decision embedded: hierarchy
-records carry no owner column — ownership is expressed solely through
-grants (§4.4) — say "agreed" or name the ownership model you want.

docs/requirements/identity-lifecycle.md

@@ -0,0 +1,328 @@
+# Identity Account-Lifecycle Contract
+
+Status: DRAFT — awaiting ratification (webui-audit S2, contract 4 of 9).
+Authority: PRD D10 (better-auth is the account system of record), Q1 ruled O1
+by Jason 2026-08-26 (webui-audit T10). This document turns that ruling into
+enforceable policy. It also carries the bootstrap/first-admin invariant from
+issue #1430, folded in here after PR #1431's independent review showed the
+quick-fix approach was insufficient.
+
+Revision 2: addresses the 9 findings of the independent review
+(`fleet/lanes/webui-audit/findings/pr1433-review.md`) — epoch enforcement
+tightened (§3), canonical email split from provider claims (§5), external
+principal keyed by issuer+subject with DB uniqueness and link step-up (§6),
+JIT default precedence and first-admin SSO path defined (§2, §4),
+deactivation made measurable (§7.1), deletion kept in scope and the existing
+hard-delete endpoint required to fail closed (§7.3), workspace identity
+reconciled with the native-kanban SOT (§1.4), verification matrix expanded
+(§8), factual labels corrected (§7.3, §8.1).
+
+Revision 3: addresses the residuals and new findings of the revision-2
+re-review (`fleet/lanes/webui-audit/findings/pr1433-review-r2.md`) —
+`users.emailVerified` added to the canonical set with a defined reset rule on
+email change (§5.1–5.2), external-principal uniqueness moved to
+(issuer, subject) (§6.1), "can actually use" defined (§6.5), the shipped
+delete affordances (web admin page, `mosaic auth users delete`) required to
+be removed or disabled with a defined user-visible state (§7.3), the
+admin-creation switch removed in favor of plain admin authorization (§2.3),
+and §8 extended with observables for IdP removal, forward-auth non-use,
+first-admin SSO, wizard-recorded JIT choice, the admin-guide statement, and
+positive/expiry-bound step-up cases.
+
+Scope: account creation, bootstrap, federated login, account linking, claim
+mapping, deactivation, and (minimally) deletion gating. Out of scope: RBAC
+grant semantics (contract 2), wizard UX flow (contract 3), hierarchy schema
+(contract 1), sensitive-data custody (contract 7 / D14).
+
+## 1. System of record
+
+1. better-auth's tables (`users`, `accounts`, `sessions`, `verifications`) are
+   the only account system of record. All foreign keys reference `users.id`.
+2. External IdPs (Authentik or any OIDC provider) are login methods, attached
+   through better-auth's generic-OAuth plugin (`packages/auth/src/sso.ts`).
+   They never own accounts. Removing an IdP removes a login method, not users.
+3. The forward-auth perimeter shim is a deployment measure. Once in-app OIDC
+   is configured for a deployment, the shim is demoted: it may stay as network
+   perimeter, but no application code may read identity from its headers.
+4. **Account ≠ workspace membership.** Creating an account (by any path:
+   bootstrap, sign-up, invite, JIT, admin creation) creates no workspace, no
+   hierarchy grant, and no workspace-scoped authority (native-kanban SOT
+   REQ-TEN-001 / REQ-ID-001). The better-auth `role` field is a platform/auth
+   role (`member` | `admin`), not workspace membership. Workspace grants are
+   defined by contract 2; until then a fresh account can authenticate and
+   holds no workspace authority.
+
+## 2. Registration gating
+
+Measured current state on `next`: `emailAndPassword.enabled: true` with no
+gating — anyone who can reach the Gateway can create an account via
+`POST /api/auth/sign-up/email` and receives role `member`.
+
+Contract:
+
+1. A single server-side setting `registration_mode` with values
+   `open | invite | closed`. It lives in the database (admin-mutable at
+   runtime), not in env config.
+2. Default after bootstrap: `closed`. The wizard (contract 3) may set a
+   different mode during setup, recorded as an explicit operator choice.
+   While the bootstrap epoch is open (§3), the effective mode is `closed`
+   regardless of any stored value: the setting takes effect only after the
+   epoch completes.
+3. `closed` blocks self-service email/password sign-up. It does not block
+   admin-created users or OIDC JIT (§4). Post-bootstrap admin creation is
+   gated by admin authorization alone — there is no separate switch for it.
+   JIT is gated by its per-provider flag (§4.1). All user-creating paths are
+   closed while the bootstrap epoch is open (§3).
+4. `invite` requires a single-use, expiring invite token bound to an email
+   address. Invite issuance is an admin operation and is audit-logged.
+5. Enforcement point: a better-auth hook (or equivalent middleware executed
+   inside the auth handler path), not a Gateway route guard in front of it —
+   the raw `/api/auth/*` handler must be incapable of bypassing the gate.
+
+## 3. Bootstrap / first-admin invariant (from #1430)
+
+Invariant: **the system transitions from zero users to one admin user exactly
+once per bootstrap epoch, atomically, regardless of concurrency or which code
+path writes users.**
+
+Constraints any implementation MUST satisfy (each traces to a verified defect
+in PR #1431's review, `fleet/lanes/webui-audit/findings/pr1431-review.md`):
+
+1. **Durable fail-closed epoch state, obeyed by every writer.** The epoch
+   lives in a constraint-backed one-row `bootstrap_state` table. While the
+   epoch is open, every non-bootstrap user-creating writer — better-auth
+   sign-up, OIDC JIT, admin creation — refuses, fail-closed, enforced inside
+   the writer's own path (better-auth hook for the raw handler; guard for
+   admin routes). A partial unique index or a winning epoch-transition row is
+   necessary but not sufficient on its own: neither stops an untagged insert
+   from a writer that never consulted the epoch. Both layers are required:
+   database-level transition safety (the epoch-completing write races safely
+   and at most one wins) and writer-level refusal (no path can create a user
+   without reading epoch state).
+2. **Atomic first-admin transition.** The admin user, its credential account,
+   the initial admin token, and the epoch-completed transition commit in one
+   database transaction or not at all. A better-auth call through
+   `drizzleAdapter(db)` runs on the root pool and is NOT part of any caller
+   transaction; it may be used inside the bootstrap transition only if the
+   adapter is explicitly bound to the transaction handle. Otherwise the
+   bootstrap writer must create the user rows itself within the transaction.
+3. **Pool safety.** No design may hold a pooled connection inside a
+   transaction while awaiting a write that acquires a second connection from
+   the same pool (`DB_POOL_MAX=1` is a supported configuration).
+4. **Re-runnability (D4).** Bootstrap is not a one-shot: after the first-admin
+   epoch completes, re-running the wizard reconfigures the system but never
+   re-opens the zero-user transition. "Setup already completed" is a stable,
+   testable state, and factory-reset (a future, explicitly destructive
+   operation) is the only way to open a new epoch.
+5. **No stranded partial outcome.** A failure at any point in the transition
+   leaves nothing observable (no admin user without its token, no completed
+   epoch without an admin) and setup remains retryable — this follows from
+   §3.2 and is stated separately because it is the pre-existing failure mode
+   the #1431 review verified.
+6. **First-admin via SSO (D4).** When the operator chooses SSO for the
+   initial user, the wizard executes the OIDC login as part of the bootstrap
+   transition itself: the bootstrap writer creates the account from the
+   asserted identity inside the §3.2 transaction. This path is the bootstrap
+   writer, not JIT — §4's JIT gate stays closed during the epoch and is not
+   an obstacle to D4.
+
+## 4. JIT provisioning (OIDC first login)
+
+1. A successful OIDC login with no matching account creates a user
+   just-in-time only when `jit_provisioning` is enabled for that provider.
+   The flag is per-provider and defaults off, always. There is no
+   mode-implied default: Enterprise setup enables JIT only when the wizard
+   records it as an explicit operator choice for a named provider (this
+   replaces revision 1's "Enterprise mode defaults to closed with OIDC JIT
+   enabled", which contradicted the per-provider default).
+2. JIT users receive platform role `member`, never an elevated role,
+   regardless of IdP claims (§5), and no workspace authority (§1.4).
+3. An optional per-provider email-domain allowlist constrains JIT. The
+   allowlist matches only when the IdP asserts the email with
+   `email_verified: true`; an unverified address never satisfies the
+   allowlist. Empty allowlist with JIT on means any authenticated subject at
+   that IdP gets an account — permitted, but the wizard must present it as an
+   explicit choice.
+4. JIT is disabled while the bootstrap epoch is open (§3.1). The first-admin
+   SSO path is §3.6, not JIT.
+
+## 5. Claim mapping
+
+1. **Two stores, not one.** Provider-observed claims (`email`,
+   `email_verified`, display name, avatar) are recorded per external
+   principal — keyed by issuer + subject (§6.1) — at first login and
+   refreshed at each login. The canonical account fields (`users.email`,
+   `users.emailVerified`, `users.name`, `users.image`) are set exactly once
+   at account creation and are never silently overwritten by a later login.
+   For SSO-created accounts (JIT or first-admin SSO), `users.emailVerified`
+   is set from the provider's `email_verified` claim at creation; for
+   password-created accounts it is false until the address completes
+   verification.
+2. **Canonical email changes only through an explicit workflow.** Either the
+   user-initiated email change (with verification of the new address) or an
+   admin edit. Any canonical email change — user- or admin-initiated — sets
+   `users.emailVerified` to false until the new address completes
+   verification; an admin may instead explicitly attest the address as
+   verified in the same operation, and that attestation is audit-logged. A
+   provider-claim refresh never rebinds `users.email` or
+   `users.emailVerified`; a divergence between canonical email and the latest
+   provider-observed email is surfaced per §6.4.
+3. Never mapped from IdP claims: `role` and any future authorization
+   attribute. Authorization lives in the system of record and in the RBAC
+   layer (contract 2). An IdP group/role claim may at most be recorded for
+   audit; it grants nothing.
+
+## 6. Account linking trust
+
+1. **External principal identity is issuer + subject.** A linked identity is
+   keyed by the OIDC issuer and subject claims, not by an unqualified
+   provider subject id and not by email. The linked-identity row stores the
+   issuer, and the database enforces at most one local account per
+   **(issuer, subject)** with a unique constraint on those stored columns —
+   uniqueness on (provider, subject) is insufficient because provider →
+   issuer is not one-to-one: two provider configurations can point at the
+   same issuer, and the identity must not alias across them. The current
+   non-unique `(provider_id, account_id)` index satisfies neither;
+   application-level checks without a uniqueness witness lose
+   concurrent-callback races. Each configured provider additionally binds to
+   exactly one issuer, immutable after creation (changing the issuer means
+   creating a new provider).
+2. Linking an OIDC identity to an existing account happens only in one of two
+   ways: (a) explicit link initiated by the logged-in user from settings,
+   which requires step-up: a fresh reauthentication (password or existing
+   linked method) no older than a short bound the implementation defines
+   (≤ 10 minutes) — a session cookie alone is insufficient, so a stolen
+   session cannot quietly attach a durable login method; or (b) automatic
+   link when the IdP asserts a verified email exactly matching an existing
+   account **and** the provider is marked `trusted_for_linking`
+   (per-provider flag, default off).
+3. Untrusted-provider email collision produces a login error naming the
+   conflict, not an auto-link and not a duplicate account.
+4. A linked identity whose IdP-observed email later diverges from the
+   canonical account email keeps working (the link is by issuer + subject,
+   §6.1) but the divergence is surfaced in the user's settings and audit log
+   (the per-principal claim store in §5.1 is what makes the divergence
+   representable).
+5. Unlinking a login method is refused when it would leave the account with
+   no **usable** login method. Usable means: a set password, or a linked
+   identity whose provider is currently configured and enabled on this
+   deployment. A linked identity whose provider has been removed or disabled
+   (§1.2) is not usable and does not count; setting a password first lifts
+   the refusal.
+
+## 7. Deactivation propagation
+
+1. **Deactivation (better-auth admin ban) is authoritative and bounded.**
+   Concretely:
+   - Ban and session revocation are one operation: the ban commit revokes all
+     better-auth sessions for the user. If revocation partially fails, the
+     ban itself must already be committed and every guard denies from that
+     point (fail closed); the operation is retryable.
+   - Every authenticated entry path checks banned state: HTTP session guards,
+     the admin bearer-token path (which today does not test `banned` — an
+     implementation defect this contract makes non-conformant), MCP, and
+     Socket.IO.
+   - Active socket connections are terminated or denied within 30 seconds of
+     the ban commit, or at the next inbound message on that socket, whichever
+     comes first (socket auth at connect-time only, as today, does not
+     satisfy this).
+   - The current admin ban route updates only the user row; it does not
+     conform to this section until revocation and guard coverage land.
+   - Admin tokens owned by the banned user are revoked in the same operation.
+2. Deactivation at an external IdP does not propagate automatically in this
+   contract's scope (no SCIM). Operational rule: removing a user from the IdP
+   without banning them in Mosaic leaves any password or other linked login
+   method usable — the admin guide must state this. SCIM/webhook-driven
+   propagation is future work and out of scope here.
+3. **Deletion is not deactivation, and deletion is gated here.** Account
+   deletion semantics (FK fan-out across the 21 foreign-key constraints to
+   `users.id`, spread over 19 referencing tables) require their own
+   deletion-and-retention contract, chartered as an addition to the S2 list —
+   contract 7 is the D14 sensitive-data custody contract and does not cover
+   account deletion. Until that deletion contract is ratified: the existing
+   hard-delete endpoint (`DELETE /api/admin/users/:id`) is disabled and fails
+   closed, and deactivation is the only supported removal operation. A
+   contract that merely declared deactivation "the only supported removal"
+   while the endpoint stayed live would be false on its face.
+   Disabling the endpoint alone is insufficient — its shipped callers must
+   not be left as advertised operations that now fail generically:
+   - The admin web UI delete action (`apps/web/src/app/(dashboard)/admin/page.tsx`
+     and any SPA port of it) is removed, or replaced by a disabled control
+     whose visible text states that deletion is unavailable pending the
+     deletion-and-retention contract and points at deactivation.
+   - The CLI command `mosaic auth users delete`
+     (`packages/mosaic/src/commands/auth.ts`) is removed, or exits non-zero
+     with a message stating the same and naming the deactivation command.
+   - Both surfaces expose deactivation as the supported operation.
+
+## 8. Verification requirements
+
+Every MUST above needs a bounded observable. The matrix:
+
+1. **Bootstrap invariant (§3).** Real-PostgreSQL concurrency tests using two
+   distinct physical connections (pattern:
+   `apps/gateway/src/agent/connector-lease.postgres.integration.test.ts`,
+   which runs in the `test` CI step against the `ci-postgres` PostgreSQL
+   service — note that pattern multiplexes one pooled handle, so the tests
+   here must explicitly open separate connections). Races to cover:
+   setup-vs-setup, setup-vs-raw-sign-up, setup-vs-JIT, setup-vs-admin-create.
+   Plus: liveness under `DB_POOL_MAX=1`; fault injection after each write in
+   the transition (user, credential, token, epoch) proving nothing observable
+   leaks and setup retries; wizard re-run after completion proving the
+   zero-user transition never re-opens. Mocked-transaction specs are
+   supplementary; they cannot prove serialization.
+2. **Registration gating (§2).** Spec coverage of all three modes against the
+   raw `/api/auth/` handler path, not only Gateway controllers; invite
+   lifecycle (single-use, expiry, email binding); effective-`closed` while
+   the epoch is open regardless of stored mode.
+3. **JIT (§4).** Provider flag off → no account on first OIDC login; on →
+   account with platform role `member` and no workspace grant; domain
+   allowlist rejects an unverified email claim even when the domain matches;
+   JIT refused while the epoch is open.
+4. **Claim mapping (§5).** Login refresh updates the per-principal claim
+   store and touches none of the canonical fields (`users.email`,
+   `users.emailVerified`, name, image); explicit email-change workflow is the
+   only path that rebinds canonical email; every canonical email change
+   resets `users.emailVerified` to false unless the admin attestation path
+   is taken, and that attestation appears in the audit log.
+5. **Linking (§6).** Unique-constraint witness: concurrent first-login
+   callbacks for the same (issuer, subject) yield exactly one account, and
+   two provider configurations sharing one issuer cannot create two accounts
+   for the same subject; trusted auto-link; untrusted collision error;
+   step-up both ways: an explicit link succeeds immediately after a fresh
+   reauthentication and is refused once the implementation's chosen bound
+   (≤ 10 minutes) has elapsed, and refused with no reauthentication at all;
+   unlink refusal when no remaining method is usable per §6.5, including the
+   removed-provider case, and acceptance after a password is set; divergence
+   surfaced after IdP email change.
+6. **Deactivation (§7).** Ban revokes sessions atomically or fails closed
+   (partial-failure injection); guard denial post-ban on each transport:
+   HTTP session, admin bearer token, MCP, Socket.IO; active socket terminated
+   within the 30-second/next-message bound; banned user's admin tokens
+   unusable; hard-delete endpoint returns a fail-closed error while the
+   deletion contract is unratified; the admin web UI renders no live delete
+   action (absent, or disabled with the §7.3 text) and `mosaic auth users
+delete` exits non-zero with the §7.3 message — both asserted by spec.
+7. **System of record and bootstrap edges (§1, §3.6, §4.3).** IdP removal:
+   deleting a provider configuration leaves every user row intact and every
+   other login method working (spec over the provider-config removal path).
+   Forward-auth non-use: with in-app OIDC configured, a request carrying
+   forward-auth identity headers and no session is treated as anonymous —
+   no code path derives identity from those headers (negative spec at the
+   Gateway entry). First-admin SSO: the §3.6 transition commits account,
+   token, and epoch atomically from the asserted identity, and fault
+   injection mid-transition leaves nothing observable (same harness as §8.1).
+   Wizard-recorded JIT choice: enabling JIT for a provider writes an
+   explicit per-provider operator-choice record, and no mode selection
+   enables it implicitly (assert the stored record, not UI behavior).
+8. **Documentation observable (§7.2).** The admin guide contains the
+   IdP-removal-does-not-deactivate statement; verified by a docs assertion
+   (content check in CI or an enumerated review-checklist item on the
+   implementing PR) — a MUST about documentation needs a checkable artifact,
+   not intent.
+
+## Ruling request
+
+Ratify sections 1–8 as written, with one decision embedded: registration
+defaults to `closed` after bootstrap (§2.2) — say "agreed" or name the mode
+you want as the default.

docs/requirements/rollup-projection.md

@@ -0,0 +1,351 @@
+# Roll-up Projection Contract (S2 contract 8)
+
+Status: DRAFT — awaiting ratification (webui-audit S2, contract 8 of 9).
+Authority: `native-kanban-sot.md` §8 (A1 amendment) — "task and status
+visualization bubbles up the hierarchy as aggregation over workspaces
+the reader is authorized on" (§8.1.3); roll-up is never a write and
+bubble-up views are generated projections, non-authoritative and never
+import sources (§8.2.2); the express, narrow carve-out from the
+portfolio-analytics non-goal covers per-workspace task counts and
+statuses aggregated up the parent chain over readable workspaces, and
+nothing beyond that boundary (§8.2.4); acceptance requires that roll-up
+endpoints cannot mutate state and that a reader sees aggregates only
+over workspaces they are authorized on, with no cross-tenant existence
+oracles (§8.3). A5 rank 5 names the deliverable: an authorized
+read-only roll-up query over only readable workspaces, at every
+hierarchy level, as its own non-mutating query tool, dependent on ranks
+1–3.
+
+Revision 2 (terra review F1–F7): membership-only readability is now
+workspace-local — it contributes at the workspace node only and never
+promotes ancestor visibility; upward aggregation requires an effective
+chain role, and §1 defines direct vs effective grants in contract 2's
+terms (F1). The no-oracle rule gains a defined equivalence predicate
+(normalized byte equality with an enumerated volatile-field set) and a
+partial-scope hidden-sibling witness (F2). §2.5 enumerates the closed
+semantic result and denial schemas field-by-field, including the
+explicit-zero representation (F3). Cache invalidation, when a cache
+exists, is witnessed per invalidator class (F4). Non-authoritative and
+never-gate rules gain an import-graph/data-flow witness, and the
+mutation check is aligned to contract 1 §6.7's both-table zero-write
+assertion (F5). The fixture gains a second estate with distinct counts
+and explicit company-, estate-, project-grant, and membership cases
+(F6). The §5.3 legacy-row exclusion and pre-rank no-obligation rules
+are disclosed as drafting additions (F7).
+
+Revision 3 (terra re-review residuals): the partial-scope witnesses are
+reconstructed at levels where chain grants can actually differ —
+platform-project siblings under one estate and estate siblings under
+one company — because contract 1 §3.1/§3.4 defines no workspace-level
+grant target, so no reader can hold a chain grant on two of three
+sibling workspaces (F2). §2.5 now defines one field-exact recursive
+record — every node, including the queried node and every leaf, is the
+same five-field shape with a required, deterministically ordered
+`children` array that is empty at workspaces — and the whole-result
+rules (no optional fields, denial envelope, wire faithfulness) are
+their own §2.6 at section scope (F3). The fixture assigns workspaces
+to named platform-projects, and §6.1's grant-level cases are the three
+levels contract 1 defines, with workspace-level access covered by the
+membership case and stated as having no direct chain grant (F6).
+
+This contract binds the projection semantics (§2), reader authorization
+semantics (§3), read-only enforcement (§4), dependencies and phase
+timing (§5), witnesses (§6), and disclosed drafting additions (§7). It
+defines the roll-up only: hierarchy shape stays with contract 1
+(`hierarchy-schema.md`), grant vocabulary and evaluation with contract 2
+(`rbac-grant-model.md`), the task lifecycle and status taxonomy with
+`native-kanban-sot.md`'s typed surface, and the tool↔Gateway mapping
+row with contract 5 (`tool-gateway-mapping.md`).
+
+## 1. Definitions
+
+1. **Roll-up**: the read-only projection of per-workspace task counts
+   by status, aggregated up the contract 1 parent chain (workspace →
+   platform-project → estate → company).
+2. **Effective chain role** (at a node, for a reader): the role
+   contract 2 §3 evaluation yields at that node — from a grant on the
+   node itself (a **direct grant**) or from a grant on an ancestor
+   whose domain covers it (an **inherited grant**, contract 2 §3.2).
+   The role vocabulary is contract 2 §2's; this contract adds no role
+   and no new authority source.
+3. **Chain-readable workspace** (for a reader): a workspace where the
+   reader's effective chain role permits reading task state.
+4. **Member-readable workspace** (for a reader): a workspace readable
+   only through workspace membership under the SOT's own membership
+   rules (REQ-ID-001), with no effective chain role. Membership
+   confers workspace-local semantics only (contract 2 §3.1, §7.4): it
+   never contributes authority, visibility, or aggregation upward.
+5. **Aggregation scope** (of a hierarchy node, for a reader): the set
+   of chain-readable workspaces in that node's descendant subtree;
+   plus, when the node is itself a workspace, that workspace if it is
+   chain-readable or member-readable. A member-readable workspace
+   therefore contributes to exactly one node's aggregation scope: its
+   own.
+6. **Projection**: a generated, non-authoritative view in the sense of
+   `native-kanban-sot.md` §3 invariant 5 — derived from SOT rows,
+   never an import source, never authoritative.
+
+## 2. Projection semantics
+
+1. **Aggregate content.** The roll-up for a node reports, per
+   workspace in the reader's aggregation scope and as subtree totals:
+   task counts keyed by the typed lifecycle's status values (owned by
+   `native-kanban-sot.md`; this contract introduces no status), and
+   nothing else. Direct count/status aggregation is the entire
+   surface.
+2. **Every level.** The roll-up is queryable at workspace,
+   platform-project, estate, and company level. A node's totals equal
+   the sum over its aggregation scope; chain resolution is contract 1
+   §2.5's (every workspace resolves to exactly one chain), so no
+   workspace is counted twice and none is orphaned.
+3. **Carve-out boundary.** Everything beyond direct count/status
+   aggregation — metrics, trends, forecasting, scoring, velocity,
+   cross-workspace derived analytics, dashboards computed across
+   workspaces — remains a `native-kanban-sot.md` §6 non-goal
+   (§8.2.4). The response schema is closed (§2.5; §6.7 witness):
+   adding any field is an amendment to this contract.
+4. **Non-authoritative.** No consumer may treat roll-up output as a
+   source of record; it is recomputable at any time from SOT rows and
+   is never imported, persisted as authoritative state, or used to
+   gate or deny work (witness §6.8 — both the write-path and the
+   decision-path prohibitions are witnessed).
+5. **Closed semantic schema.** The successful result is exactly one
+   **roll-up node record**, a single recursive shape used at every
+   depth. A roll-up node record consists of exactly these five
+   fields, and no others:
+   - `id`: the node's identifier.
+   - `type`: one of the four contract 1 levels.
+   - `name`: the node's name.
+   - `totals`: one entry per status value of the typed lifecycle —
+     every status key present, a count of zero represented explicitly
+     as `0`, never by key absence. At a workspace node, `totals` is
+     that workspace's own counts; at any other node, `totals` is the
+     sum over the node's aggregation scope (§2.2). This is how §2.1's
+     "per workspace and as subtree totals" content is carried:
+     per-workspace counts are the leaf records' `totals`, subtree
+     totals are the interior records' `totals`.
+   - `children`: a required array, present on EVERY node record. Its
+     elements are the reader-visible (§3.2) child nodes of this node,
+     each itself a complete roll-up node record, recursing down to
+     the workspaces in the reader's aggregation scope. At a workspace
+     node the array is exactly `[]` — a workspace record never has
+     children. The array is ordered deterministically, ascending by
+     `id`; the implementing PR asserts that ordering. A node outside
+     §3.2 visibility never appears at any depth.
+
+   The queried node's record IS the whole result — there is no
+   wrapper field around it.
+
+6. **Whole-result rules.** There are no optional result fields at any
+   depth. The denial/nonexistent response is the contract 5 §4.2
+   not-found-class error envelope with no fields beyond that
+   envelope. The wire DTO is expressed under contract 5 §4.1, and
+   MUST be a faithful serialization of exactly the §2.5 recursive
+   record: a wire field with no corresponding semantic field is a
+   conformance defect.
+
+## 3. Reader authorization semantics
+
+1. **Scope rule.** A reader's roll-up over any node aggregates ONLY
+   the reader's aggregation scope (§1.5). An unreadable workspace
+   contributes nothing to any total — not a count, not a row, not a
+   presence marker. A member-readable workspace contributes only at
+   the workspace node itself (§1.4–§1.5): querying it directly
+   succeeds; it never appears in, and never adds to, any ancestor's
+   response for that reader.
+2. **Node visibility.** A node appears in a roll-up response iff the
+   reader's aggregation scope at that node is non-empty, or the
+   reader holds an effective chain role at the node (§1.2 — direct or
+   inherited; contract 2 §3.2 makes a grant's domain the node and its
+   subtree, so an ancestor grant makes empty descendants visible per
+   the ruling). Per the ruling below, a node with an effective chain
+   role but an empty aggregation scope appears with zero counts.
+   Workspace membership alone never makes any non-workspace node
+   visible. A node where the reader has neither an effective chain
+   role nor a non-empty aggregation scope does not appear at all.
+3. **No existence oracle.** The response MUST NOT disclose the
+   existence, count, name, or any property of unreadable workspaces
+   or of nodes outside §3.2 visibility — no "N workspaces hidden"
+   fields, no total-vs-visible discrepancy fields. A query naming a
+   node outside §3.2 visibility MUST satisfy the §3.4 response
+   equivalence with a query naming a nonexistent node (fail closed,
+   `rbac-grant-model.md` §3.5 pattern: a decision path that cannot
+   read grant state denies).
+4. **Response equivalence predicate.** Two responses are equivalent
+   when they carry the identical HTTP status, the identical contract
+   5 §4.2 error code, and byte-identical bodies after normalizing
+   exactly the declared volatile envelope fields — correlation id and
+   response timestamp, and nothing else. The implementing PR declares
+   that volatile-field list in the witness; any additional
+   normalization is a conformance defect. This is contract 5 §4.2's
+   same code/status/shape rule made executable.
+5. **Live evaluation.** Readability is evaluated per contract 2 §3.5
+   (live rows or transactionally-invalidated cache). Revocation
+   propagates per contract 2 §6: the next roll-up query decided after
+   the revoking transaction commits excludes the revoked scope.
+
+## 4. Read-only enforcement
+
+1. **Never a write.** No roll-up path may mutate, claim, order, or
+   gate work in any workspace (§8.2.2). The roll-up ships as a
+   non-mutating query tool (A5 rank 5) — a query surface with no
+   command counterpart.
+2. **Mechanical enforcement.** The implementing PR executes roll-up
+   database work inside read-only transactions (or an equivalently
+   privilege-restricted path), so a mutation attempt fails at the
+   database boundary, not only by convention.
+3. **Freshness.** v1 computes the roll-up live from SOT rows at query
+   time. A cache is an implementation option only if it is
+   invalidated in the same transaction as any task, hierarchy, grant,
+   or membership mutation that affects it (each invalidator class
+   witnessed, §6.5), and it is never authoritative (§1.6).
+
+## 5. Dependencies and phase timing
+
+1. The roll-up depends on A5 ranks 1–3: contract 1's hierarchy tables
+   (the parent chain), contract 2's evaluator (readability), and the
+   typed Kanban lifecycle (the task state being counted). It ships
+   after them and reads their surfaces; it defines none of them.
+2. The roll-up query is one tool with one Gateway mapping row under
+   contract 5's regime (request/result/error/audit contracts there);
+   this contract binds its semantics (§2.5 defines the semantic
+   fields the contract 5 §4.1 DTO serializes), not its wire encoding.
+3. Legacy task rows outside the typed lifecycle are not aggregated;
+   the roll-up begins counting a workspace's tasks when they exist in
+   the typed surface. No roll-up obligation attaches to v1 before
+   ranks 1–3 exist. Both rules are drafting additions disclosed in §7
+   (they trace to no §8 sentence).
+
+## 6. Verification requirements
+
+Binding on the implementing PRs. Every witness names, in its
+implementation, the exact endpoints/tools, tables, and fixtures it
+exercises. The base fixture seeds two companies; under company A **two
+estates with distinct, non-identical count profiles**: estate A1 with
+two platform-projects — P1 holding workspaces W1 and W2, P2 holding
+workspace W3 — and estate A2 with one platform-project P3 holding one
+workspace W4, all with known task counts across at least three
+statuses; under company B one workspace.
+
+1. **Correctness witnesses:** for a reader holding a direct company-A
+   grant, roll-up totals at every level equal the seeded sums — each
+   workspace, each platform-project, estate A1 and estate A2
+   separately (their distinct profiles asserted distinct), and the
+   company total equal to A1+A2 — keyed by the typed status values,
+   with no double count across the chain. For a reader holding a
+   direct estate-A1 grant, the estate-A1 result equals the A1 sum and
+   a company-A query returns company A with exactly A1's contribution
+   (estate A2 invisible). Each of the three chain grant levels
+   contract 1 §3.1 defines — company, estate, platform-project
+   (below, §6.2) — has an explicit direct-grant case, none simulated
+   by unioning lower access. Workspace-level access has NO direct
+   chain grant (contract 1 §3.1/§3.4 define no workspace grant
+   target) and is covered by the §6.2 membership case.
+2. **Scope witnesses:** a reader with a direct grant on
+   platform-project P1 only sees exactly P1's subtree counts
+   (W1+W2): a P1 query returns W1+W2; an estate-A1 query returns the
+   estate node with exactly P1's contribution, sibling project P2 and
+   its workspace W3 absent at every depth; a company-A query likewise
+   carries only P1's contribution. An estate-sibling case: a reader
+   with a direct grant on estate A1 only queries company A and
+   receives exactly A1's contribution, estate A2 absent. (Chain
+   grants exist only at company, estate, and platform-project —
+   contract 1 §3.1 — so partial scope among SIBLING WORKSPACES of
+   one project is not constructible by grants and is not witnessed;
+   the constructible partial-scope cases are the project- and
+   estate-sibling ones above.) **Membership locality (§1.4):** a member-only reader queries
+   the workspace directly and receives its counts; the same reader
+   querying the workspace's parent (or any ancestor) receives the
+   §3.4-equivalent nonexistent-node response, and no ancestor
+   response for any other reader changes because of that membership.
+3. **No-oracle witnesses:** the P1-only reader's estate-A1 response
+   above contains no field disclosing P2's or W3's existence
+   (closed-schema comparison against an estate-A1-granted reader's
+   response: identical field set, differing only in counts and
+   visible nodes). **Partial-scope hidden node:** the P1-only reader
+   — who sees estate A1 and the P1 subtree — queries hidden sibling
+   project P2 by its real id, and separately hidden workspace W3 by
+   its real id; each response satisfies the §3.4 equivalence
+   predicate against the same query naming a nonexistent id, under
+   one fixed request context with the declared volatile-field
+   normalization. **Cross-tenant:** an unauthorized reader naming company B receives
+   a response §3.4-equivalent to naming a nonexistent id. Each
+   equivalence check is executable byte comparison after the declared
+   normalization, not a shape judgment.
+4. **Empty-vs-hidden witness (ruling):** a reader granted (direct
+   chain grant) on an empty platform-project receives it with zero
+   counts — every status key present at `0` (§2.5); with the grant
+   deleted, the same query returns the §3.4-equivalent
+   nonexistent-node response. An inherited-grant case: a company
+   grant makes an empty descendant platform-project visible with zero
+   counts.
+5. **Cache-invalidation witnesses (conditional):** bound only if the
+   implementation caches — for EACH invalidator class, prime the
+   cache, commit one mutation of that class, and assert the next
+   query reflects it: a task status change, a task creation, a
+   membership removal (the member-readable workspace disappears from
+   its own node's next query), a workspace reparenting (both old and
+   new parent totals correct), and a grant revocation. A live
+   (cacheless) v1 implementation records that fact and the witnesses
+   bind at the PR that introduces a cache.
+6. **Mutation witnesses:** the roll-up surface rejects every mutating
+   verb/command; a crafted attempt to issue a write through the
+   roll-up's database path fails at the read-only boundary (§4.2);
+   after any roll-up query, the row diff is empty across BOTH the
+   workspace tables and the hierarchy tables (contract 1 §6.7's
+   both-table zero-write assertion).
+7. **Closed-schema witness:** the response is asserted field-exact
+   against the §2.5 recursive record at every depth — exactly
+   `id`/`type`/`name`/`totals`/`children` on every node, every typed
+   status present with explicit zeros, `children: []` at every
+   workspace record, the declared ascending-`id` ordering, no
+   wrapper field — and a response carrying any field outside the
+   record at any depth fails the assertion (carve-out boundary,
+   §2.3). The denial envelope is asserted field-exact against
+   contract 5 §4.2's envelope (§2.6).
+8. **Non-authoritative and never-gate witnesses:** (a) a static
+   production import-graph inventory (hierarchy contract §6.3 style,
+   production code over `apps/` and `packages/`, tests excluded)
+   shows no production module imports the roll-up query module or its
+   result DTO into any SOT write path, any authorization/gating
+   decision path, or any persistence beyond the response lifetime —
+   asserted in both directions (the roll-up module's consumers are
+   enumerated and each is a presentation surface); (b) a behavioral
+   probe: with roll-up output artificially perturbed (test double),
+   no authorization outcome and no work-gating decision anywhere in
+   the fixture suite changes — proving no gate consumes it.
+9. **Revocation witness:** after revoking the grant that made a
+   subtree readable, the next roll-up query excludes it (contract 2
+   §6.2 bound).
+
+## 7. Drafting additions (PRD §12.1 disclosure)
+
+Proposed drafting additions, visible here for ratification, each
+severable; the aggregation itself, its authorization scope, its
+read-only nature, and the no-oracle acceptance are traced to
+`native-kanban-sot.md` §8 and are not additions:
+
+1. The §3.2 node-visibility rule and the granted-but-empty behavior
+   (the ruling below).
+2. The §3.3–§3.4 nonexistent-node response equivalence, with its
+   normalized-byte-equality predicate, as the concrete no-oracle
+   mechanism.
+3. The §4.2 read-only-transaction mechanical enforcement.
+4. The §4.3 cache option with transactional invalidation and the
+   §6.5 per-invalidator witnesses.
+5. The §2.5 closed response schema as an amendment boundary.
+6. The §1.4 membership-locality rule — membership-only readability
+   contributes at the workspace node only (this contract's
+   reconciliation of `native-kanban-sot.md` §8.1.3 "authorized on"
+   with contract 2 §3.1/§7.4's workspace-local membership).
+7. The §5.3 legacy-row exclusion and the §5.3 pre-rank no-obligation
+   rule.
+
+## Ruling request
+
+Ruling requested (one decision): shall a node the reader holds an
+effective chain role on (direct or inherited, §1.2) but whose
+aggregation scope is empty appear in the roll-up with zero counts
+(recommended — it lets the UI show a granted-but-empty subtree
+honestly) — or, as the alternative, be indistinguishable from a
+nonexistent node until it contains a readable workspace?