beadhub 0.1.0__py3-none-any.whl

beadhub/internal_auth.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import logging
+import os
+import uuid
+from typing import Optional, TypedDict
+
+from fastapi import HTTPException, Request
+
+logger = logging.getLogger(__name__)
+
+INTERNAL_AUTH_HEADER = "X-BH-Auth"
+INTERNAL_PROJECT_HEADER = "X-Project-ID"
+INTERNAL_USER_HEADER = "X-User-ID"
+INTERNAL_API_KEY_ID_HEADER = "X-API-Key"
+INTERNAL_ACTOR_ID_HEADER = "X-Aweb-Actor-ID"
+
+
+class InternalAuthContext(TypedDict):
+    project_id: str
+    principal_type: str  # "u" or "k"
+    principal_id: str
+    actor_id: str
+
+
+def _get_internal_auth_secret() -> Optional[str]:
+    # Some embedded/proxy deployments may reuse SESSION_SECRET_KEY to sign X-BH-Auth.
+    # For standalone OSS this is typically unset.
+    return os.getenv("BEADHUB_INTERNAL_AUTH_SECRET") or os.getenv("SESSION_SECRET_KEY")
+
+
+def _internal_auth_header_value(
+    *, secret: str, project_id: str, principal_type: str, principal_id: str, actor_id: str
+) -> str:
+    msg = f"v2:{project_id}:{principal_type}:{principal_id}:{actor_id}"
+    sig = hmac.new(
+        secret.encode("utf-8"),
+        msg.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+    return f"{msg}:{sig}"
+
+
+def parse_internal_auth_context(request: Request) -> Optional[InternalAuthContext]:
+    """Parse and validate proxy-injected auth context headers for BeadHub OSS.
+
+    This is intended for proxy/wrapper deployments where the wrapper authenticates the caller
+    (JWT/cookie/API key) and injects project scope to the core service.
+
+    The core MUST treat these headers as untrusted unless `X-BH-Auth` validates.
+    """
+    internal_auth = request.headers.get(INTERNAL_AUTH_HEADER)
+    if not internal_auth:
+        return None
+
+    # In standalone OSS mode the internal auth secret is intentionally unset. Treat any
+    # client-supplied internal headers as untrusted and ignore them rather than
+    # failing with a 500.
+    secret = _get_internal_auth_secret()
+    if not secret:
+        path = request.scope.get("path") or ""
+        logger.warning(
+            "Ignoring %s header because BEADHUB_INTERNAL_AUTH_SECRET is not configured (path=%s)",
+            INTERNAL_AUTH_HEADER,
+            path,
+        )
+        return None
+
+    project_id = request.headers.get(INTERNAL_PROJECT_HEADER)
+    if not project_id:
+        raise HTTPException(status_code=401, detail="Authentication required")
+    try:
+        project_id = str(uuid.UUID(project_id))
+    except ValueError:
+        raise HTTPException(status_code=401, detail="Authentication required")
+
+    user_id = request.headers.get(INTERNAL_USER_HEADER)
+    api_key_id = request.headers.get(INTERNAL_API_KEY_ID_HEADER)
+    if user_id:
+        try:
+            user_id = str(uuid.UUID(user_id))
+        except ValueError:
+            raise HTTPException(status_code=401, detail="Authentication required")
+        principal_type = "u"
+        principal_id = user_id
+    elif api_key_id:
+        try:
+            api_key_id = str(uuid.UUID(api_key_id))
+        except ValueError:
+            raise HTTPException(status_code=401, detail="Authentication required")
+        principal_type = "k"
+        principal_id = api_key_id
+    else:
+        raise HTTPException(status_code=401, detail="Authentication required")
+
+    actor_id = request.headers.get(INTERNAL_ACTOR_ID_HEADER)
+    if not actor_id:
+        raise HTTPException(status_code=401, detail="Authentication required")
+    try:
+        actor_id = str(uuid.UUID(actor_id))
+    except ValueError:
+        raise HTTPException(status_code=401, detail="Authentication required")
+
+    expected = _internal_auth_header_value(
+        secret=secret,
+        project_id=project_id,
+        principal_type=principal_type,
+        principal_id=principal_id,
+        actor_id=actor_id,
+    )
+    if not hmac.compare_digest(internal_auth, expected):
+        raise HTTPException(status_code=401, detail="Authentication required")
+
+    return {
+        "project_id": project_id,
+        "principal_type": principal_type,
+        "principal_id": principal_id,
+        "actor_id": actor_id,
+    }

beadhub/jsonl.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import json
+from typing import Any, List
+
+
+class JSONLParseError(ValueError):
+    """Raised when JSONL parsing fails with line context."""
+
+
+def _check_json_depth(obj: object, max_depth: int, current_depth: int = 0) -> bool:
+    """Return True if JSON nesting depth is within limit."""
+
+    if current_depth >= max_depth:
+        return False
+    if isinstance(obj, dict):
+        for v in obj.values():
+            if not _check_json_depth(v, max_depth, current_depth + 1):
+                return False
+        return True
+    if isinstance(obj, list):
+        for item in obj:
+            if not _check_json_depth(item, max_depth, current_depth + 1):
+                return False
+        return True
+    return True
+
+
+def parse_jsonl(
+    content: str,
+    *,
+    max_depth: int = 10,
+    max_count: int = 10000,
+) -> List[dict[str, Any]]:
+    """
+    Parse JSONL content into a list of dicts.
+
+    - Skips empty lines
+    - Validates max_count incrementally (fails fast)
+    - Validates per-record nesting depth
+
+    Raises:
+        JSONLParseError: on invalid JSON, recursion errors, or depth/count violations
+    """
+
+    issues: list[dict[str, Any]] = []
+    for line_num, line in enumerate(content.splitlines(), start=1):
+        line = line.strip()
+        if not line:
+            continue
+        if len(issues) >= max_count:
+            raise JSONLParseError(f"Too many issues: exceeds limit of {max_count}")
+        try:
+            issue = json.loads(line)
+        except json.JSONDecodeError as e:
+            raise JSONLParseError(f"Invalid JSON on line {line_num}: {e.msg}") from e
+        except RecursionError as e:
+            raise JSONLParseError(
+                f"JSON nesting too deep on line {line_num}: exceeds recursion limit"
+            ) from e
+        if not isinstance(issue, dict):
+            raise JSONLParseError(f"JSON on line {line_num} must be an object")
+        if not _check_json_depth(issue, max_depth):
+            raise JSONLParseError(
+                f"JSON nesting depth exceeds limit ({max_depth}) on line {line_num}"
+            )
+        issues.append(issue)
+    return issues

beadhub/logging.py

@@ -0,0 +1,62 @@
+"""Structured logging configuration for BeadHub."""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+
+class JSONFormatter(logging.Formatter):
+    """Format log records as JSON for structured logging."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        log_data: dict[str, Any] = {
+            "timestamp": datetime.fromtimestamp(record.created, timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "function": record.funcName,
+            "line": record.lineno,
+        }
+
+        if record.exc_info:
+            log_data["exception"] = self.formatException(record.exc_info)
+
+        if hasattr(record, "request_id"):
+            log_data["request_id"] = record.request_id
+
+        return json.dumps(log_data)
+
+
+def configure_logging(log_level: str = "INFO", json_format: bool = True) -> None:
+    """
+    Configure logging for BeadHub.
+
+    Args:
+        log_level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        json_format: If True, use JSON format. If False, use simple text format.
+    """
+    root_logger = logging.getLogger()
+    root_logger.setLevel(log_level.upper())
+
+    # Remove existing handlers
+    for handler in root_logger.handlers[:]:
+        root_logger.removeHandler(handler)
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setLevel(log_level.upper())
+
+    if json_format:
+        handler.setFormatter(JSONFormatter())
+    else:
+        handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
+
+    root_logger.addHandler(handler)
+
+    # Quiet noisy libraries
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("httpcore").setLevel(logging.WARNING)
+    logging.getLogger("asyncio").setLevel(logging.WARNING)

beadhub/migrations/beads/001_initial.sql

@@ -0,0 +1,70 @@
+-- 001_initial.sql
+-- Description: Baseline BeadHub beads schema (issues)
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+CREATE TABLE IF NOT EXISTS {{tables.beads_issues}} (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+
+    -- Tenant isolation: project_id scopes all data
+    project_id UUID NOT NULL,
+
+    -- Identity: bead_id is unique within (project_id, repo, branch)
+    bead_id TEXT NOT NULL,
+    repo TEXT NOT NULL DEFAULT 'default',  -- canonical origin e.g. github.com/org/repo
+    branch TEXT NOT NULL DEFAULT 'main',
+
+    -- Issue content
+    title TEXT,
+    description TEXT,
+    status TEXT,
+    priority INTEGER,
+    issue_type TEXT,
+    assignee TEXT,
+    labels TEXT[],
+
+    -- Dependencies as JSONB for cross-repo/branch references
+    blocked_by JSONB DEFAULT '[]'::jsonb,
+    parent_id JSONB,
+
+    -- Creator attribution
+    created_by TEXT,
+
+    -- Timestamps
+    created_at TIMESTAMPTZ,
+    updated_at TIMESTAMPTZ,
+    synced_at TIMESTAMPTZ DEFAULT NOW(),
+
+    -- Bead history: who closed this bead (cross-schema FK to server.workspaces)
+    closed_by_workspace_id UUID REFERENCES server.workspaces(workspace_id) ON DELETE SET NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_beads_issues_project_repo_branch_bead
+    ON {{tables.beads_issues}}(project_id, repo, branch, bead_id);
+
+CREATE INDEX IF NOT EXISTS idx_beads_issues_project_id
+    ON {{tables.beads_issues}}(project_id);
+
+CREATE INDEX IF NOT EXISTS idx_beads_issues_status
+    ON {{tables.beads_issues}}(status);
+
+CREATE INDEX IF NOT EXISTS idx_beads_issues_project_repo
+    ON {{tables.beads_issues}}(project_id, repo);
+
+CREATE INDEX IF NOT EXISTS idx_beads_issues_parent
+    ON {{tables.beads_issues}}((parent_id->>'bead_id'))
+    WHERE parent_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_beads_issues_project_bead
+    ON {{tables.beads_issues}}(project_id, bead_id);
+
+CREATE INDEX IF NOT EXISTS idx_beads_issues_closed_by
+    ON {{tables.beads_issues}}(closed_by_workspace_id)
+    WHERE closed_by_workspace_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_beads_issues_project_status
+    ON {{tables.beads_issues}}(project_id, status);
+
+CREATE INDEX IF NOT EXISTS idx_beads_issues_project_created_by
+    ON {{tables.beads_issues}}(project_id, created_by)
+    WHERE created_by IS NOT NULL;

beadhub/migrations/beads/002_search_indexes.sql

@@ -0,0 +1,20 @@
+-- pgdbm:no-transaction
+-- 002_search_indexes.sql
+-- Description: Add indexes for bead search (q= parameter) performance
+-- Requires no-transaction mode because CREATE INDEX CONCURRENTLY
+-- cannot run inside a transaction block.
+
+-- Enable pg_trgm extension for trigram-based text search
+-- This supports efficient ILIKE queries with leading wildcards
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+
+-- GIN trigram index on title for substring search (ILIKE '%query%')
+-- Supports case-insensitive substring matching efficiently
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_beads_issues_title_trgm
+    ON {{tables.beads_issues}} USING gin (title gin_trgm_ops);
+
+-- GIN trigram index on bead_id for case-insensitive prefix search
+-- Supports ILIKE with ESCAPE clause for safely handling user input with wildcards
+-- (see _escape_like_pattern() in routes/beads.py)
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_beads_issues_bead_id_trgm
+    ON {{tables.beads_issues}} USING gin (bead_id gin_trgm_ops);

beadhub/migrations/server/001_initial.sql

@@ -0,0 +1,279 @@
+-- 001_initial.sql
+-- Description: Baseline BeadHub server schema (clean-slate split)
+--
+-- Coordination primitives (mail/chat/locks/auth keys) live in `aweb`.
+-- BeadHub owns: repos, workspaces, beads, claims, subscriptions, policies, escalations.
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+CREATE TABLE IF NOT EXISTS {{tables.projects}} (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    -- Partition key for multi-tenant SaaS (NULL for single-tenant OSS mode)
+    tenant_id UUID,
+    slug TEXT NOT NULL,
+    name TEXT,
+    -- Active policy pointer (FK added after project_policies exists)
+    active_policy_id UUID,
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    -- Soft-delete support: NULL means active
+    deleted_at TIMESTAMPTZ
+);
+
+-- Slugs unique within tenant (or globally if no tenant), for non-deleted projects.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_projects_slug_no_tenant
+    ON {{tables.projects}}(slug) WHERE tenant_id IS NULL AND deleted_at IS NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS idx_projects_slug_with_tenant
+    ON {{tables.projects}}(tenant_id, slug) WHERE tenant_id IS NOT NULL AND deleted_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_projects_active ON {{tables.projects}}(id) WHERE deleted_at IS NULL;
+
+CREATE TABLE IF NOT EXISTS {{tables.repos}} (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    -- CASCADE: repos are deleted when their project is deleted (repos without projects are invalid)
+    project_id UUID NOT NULL REFERENCES {{tables.projects}}(id) ON DELETE CASCADE,
+    origin_url TEXT NOT NULL,
+    canonical_origin TEXT NOT NULL,
+    name TEXT NOT NULL,
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    -- Soft-delete support: NULL means active, timestamp means deleted
+    -- Unique constraint retained for ON CONFLICT support in ensure_repo.
+    -- When a soft-deleted repo is re-registered, ensure_repo clears deleted_at.
+    deleted_at TIMESTAMPTZ,
+    CONSTRAINT unique_repo_per_project UNIQUE (project_id, canonical_origin)
+);
+
+CREATE INDEX IF NOT EXISTS idx_repos_project ON {{tables.repos}}(project_id);
+CREATE INDEX IF NOT EXISTS idx_repos_active ON {{tables.repos}}(project_id)
+    WHERE deleted_at IS NULL;
+
+CREATE TABLE IF NOT EXISTS {{tables.workspaces}} (
+    workspace_id UUID PRIMARY KEY,
+    -- CASCADE: workspaces are deleted when their project is deleted
+    project_id UUID NOT NULL REFERENCES {{tables.projects}}(id) ON DELETE CASCADE,
+    -- SET NULL: when repo is hard-deleted (e.g., project deletion cascade), preserve workspace for audit
+    -- When repo is soft-deleted via API, workspaces are soft-deleted manually in application code
+    repo_id UUID REFERENCES {{tables.repos}}(id) ON DELETE SET NULL,
+    alias TEXT NOT NULL,
+    human_name TEXT NOT NULL DEFAULT '',
+    role TEXT,
+    current_branch TEXT,
+    focus_apex_bead_id TEXT,
+    focus_apex_repo_name TEXT,
+    focus_apex_branch TEXT,
+    focus_updated_at TIMESTAMPTZ,
+    -- Physical location: for detecting "gone" workspaces (directory no longer exists)
+    -- Only checked for workspaces on the current hostname to avoid cross-machine false positives
+    hostname TEXT,
+    workspace_path TEXT,
+    -- Workspace classification
+    workspace_type TEXT NOT NULL DEFAULT 'agent',
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW(),
+    -- Soft-delete support: NULL means active, timestamp means deleted
+    deleted_at TIMESTAMPTZ,
+    -- Track when workspace was last seen (updated on every bdh command)
+    last_seen_at TIMESTAMPTZ,
+    CONSTRAINT chk_workspace_repo CHECK (
+        (workspace_type = 'agent' AND repo_id IS NOT NULL) OR
+        (workspace_type IN ('dashboard') AND repo_id IS NULL)
+    ),
+    CONSTRAINT chk_workspace_role_length CHECK (role IS NULL OR length(role) <= 50)
+);
+
+-- Partial unique index: aliases unique within project for non-deleted workspaces only
+CREATE UNIQUE INDEX IF NOT EXISTS idx_unique_active_alias
+    ON {{tables.workspaces}}(project_id, alias)
+    WHERE deleted_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_workspaces_alias ON {{tables.workspaces}}(alias);
+CREATE INDEX IF NOT EXISTS idx_workspaces_project ON {{tables.workspaces}}(project_id);
+CREATE INDEX IF NOT EXISTS idx_workspaces_repo ON {{tables.workspaces}}(repo_id);
+CREATE INDEX IF NOT EXISTS idx_workspaces_active ON {{tables.workspaces}}(project_id)
+    WHERE deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_workspaces_hostname ON {{tables.workspaces}}(hostname)
+    WHERE hostname IS NOT NULL AND deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_workspaces_dashboard
+    ON {{tables.workspaces}}(project_id, human_name)
+    WHERE workspace_type = 'dashboard';
+
+-- Trigger to update updated_at and enforce immutability
+CREATE OR REPLACE FUNCTION {{schema}}.update_workspace_timestamp()
+RETURNS TRIGGER AS $$
+BEGIN
+    -- Enforce immutability of key fields
+    IF NEW.project_id IS DISTINCT FROM OLD.project_id THEN
+        RAISE EXCEPTION 'project_id is immutable';
+    END IF;
+    -- repo_id can become NULL via FK SET NULL cascade (when repo is hard-deleted), but not change to different repo
+    IF NEW.repo_id IS DISTINCT FROM OLD.repo_id AND NEW.repo_id IS NOT NULL THEN
+        RAISE EXCEPTION 'repo_id is immutable (cannot change to different repo)';
+    END IF;
+    IF NEW.alias IS DISTINCT FROM OLD.alias THEN
+        RAISE EXCEPTION 'alias is immutable';
+    END IF;
+    IF NEW.workspace_type IS DISTINCT FROM OLD.workspace_type THEN
+        RAISE EXCEPTION 'workspace_type is immutable';
+    END IF;
+
+    -- Auto-soft-delete when repo_id becomes NULL (repo was hard-deleted)
+    IF OLD.repo_id IS NOT NULL AND NEW.repo_id IS NULL AND NEW.deleted_at IS NULL THEN
+        NEW.deleted_at = NOW();
+    END IF;
+
+    NEW.updated_at = NOW();
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS workspace_updated_at ON {{tables.workspaces}};
+CREATE TRIGGER workspace_updated_at
+    BEFORE UPDATE ON {{tables.workspaces}}
+    FOR EACH ROW
+    EXECUTE FUNCTION {{schema}}.update_workspace_timestamp();
+
+CREATE TABLE IF NOT EXISTS {{tables.bead_claims}} (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    -- CASCADE: claims deleted when project is deleted
+    project_id UUID NOT NULL REFERENCES {{tables.projects}}(id) ON DELETE CASCADE,
+    -- CASCADE: claims deleted when workspace is deleted
+    workspace_id UUID NOT NULL REFERENCES {{tables.workspaces}}(workspace_id) ON DELETE CASCADE,
+    alias TEXT NOT NULL,
+    human_name TEXT NOT NULL,
+    bead_id TEXT NOT NULL,
+    -- Apex reference for fast team status listings
+    apex_bead_id TEXT,
+    apex_repo_name TEXT,
+    apex_branch TEXT,
+    claimed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    -- Multiple workspaces can claim the same bead (coordinated work with --:jump-in)
+    UNIQUE(project_id, bead_id, workspace_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_bead_claims_workspace
+    ON {{tables.bead_claims}}(workspace_id, claimed_at DESC);
+CREATE INDEX IF NOT EXISTS idx_bead_claims_project ON {{tables.bead_claims}}(project_id);
+
+CREATE TABLE IF NOT EXISTS {{tables.escalations}} (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    project_id UUID NOT NULL REFERENCES {{tables.projects}}(id) ON DELETE CASCADE,
+    workspace_id UUID NOT NULL REFERENCES {{tables.workspaces}}(workspace_id) ON DELETE CASCADE,
+    alias TEXT NOT NULL,
+    member_email TEXT,
+    subject TEXT NOT NULL,
+    situation TEXT NOT NULL,
+    options JSONB,
+    status TEXT DEFAULT 'pending',
+    response TEXT,
+    response_note TEXT,
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    responded_at TIMESTAMPTZ,
+    expires_at TIMESTAMPTZ
+);
+
+CREATE INDEX IF NOT EXISTS idx_escalations_status ON {{tables.escalations}}(status);
+CREATE INDEX IF NOT EXISTS idx_escalations_member ON {{tables.escalations}}(member_email);
+CREATE INDEX IF NOT EXISTS idx_escalations_workspace ON {{tables.escalations}}(workspace_id);
+CREATE INDEX IF NOT EXISTS idx_escalations_alias_created
+    ON {{tables.escalations}}(alias, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS {{tables.subscriptions}} (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    project_id UUID NOT NULL REFERENCES {{tables.projects}}(id) ON DELETE CASCADE,
+    workspace_id UUID NOT NULL REFERENCES {{tables.workspaces}}(workspace_id) ON DELETE CASCADE,
+    alias TEXT NOT NULL,
+    bead_id TEXT NOT NULL,
+    repo TEXT,
+    event_types TEXT[] NOT NULL DEFAULT '{status_change}',
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_subscriptions_unique
+    ON {{tables.subscriptions}}(project_id, workspace_id, bead_id, COALESCE(repo, ''));
+CREATE INDEX IF NOT EXISTS idx_subscriptions_bead
+    ON {{tables.subscriptions}}(project_id, bead_id, repo);
+CREATE INDEX IF NOT EXISTS idx_subscriptions_workspace
+    ON {{tables.subscriptions}}(project_id, workspace_id, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS {{tables.notification_outbox}} (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    -- Tenant isolation
+    project_id UUID NOT NULL REFERENCES {{tables.projects}}(id) ON DELETE CASCADE,
+    -- Event details
+    event_type TEXT NOT NULL DEFAULT 'bead_status_change',
+    -- Full payload for the notification (bead_id, status change, etc.)
+    payload JSONB NOT NULL,
+    -- Target workspace for the notification (no FK - subscriptions may outlive workspaces)
+    recipient_workspace_id UUID NOT NULL,
+    recipient_alias TEXT NOT NULL,
+    -- Processing status
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'processing', 'completed', 'failed')),
+    attempts INTEGER NOT NULL DEFAULT 0,
+    last_error TEXT,
+    -- Timestamps
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    processed_at TIMESTAMPTZ,
+    -- Message ID if successfully sent (no FK - messages may be deleted)
+    message_id UUID
+);
+
+CREATE INDEX IF NOT EXISTS idx_notification_outbox_pending
+    ON {{tables.notification_outbox}}(project_id, status, attempts, created_at)
+    WHERE status IN ('pending', 'failed');
+CREATE INDEX IF NOT EXISTS idx_notification_outbox_completed
+    ON {{tables.notification_outbox}}(project_id, status, processed_at)
+    WHERE status = 'completed';
+
+CREATE TABLE IF NOT EXISTS {{tables.audit_log}} (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    project_id UUID NOT NULL REFERENCES {{tables.projects}}(id) ON DELETE CASCADE,
+    workspace_id UUID REFERENCES {{tables.workspaces}}(workspace_id) ON DELETE SET NULL,
+    event_type TEXT NOT NULL,
+    alias TEXT,
+    member_email TEXT,
+    resource TEXT,
+    bead_id TEXT,
+    details JSONB,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_log_created ON {{tables.audit_log}}(created_at);
+CREATE INDEX IF NOT EXISTS idx_audit_log_alias ON {{tables.audit_log}}(alias);
+CREATE INDEX IF NOT EXISTS idx_audit_log_project ON {{tables.audit_log}}(project_id);
+
+CREATE TABLE IF NOT EXISTS {{tables.project_policies}} (
+    policy_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    project_id UUID NOT NULL REFERENCES {{tables.projects}}(id) ON DELETE CASCADE,
+    version INT NOT NULL,
+    bundle_json JSONB NOT NULL,
+    created_by_workspace_id UUID REFERENCES {{tables.workspaces}}(workspace_id) ON DELETE SET NULL,
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW(),
+    CONSTRAINT project_policies_version_unique UNIQUE (project_id, version)
+);
+
+-- Add FK after project_policies to avoid circular dependency during create
+ALTER TABLE {{tables.projects}}
+    ADD CONSTRAINT fk_projects_active_policy
+    FOREIGN KEY (active_policy_id)
+    REFERENCES {{tables.project_policies}}(policy_id) ON DELETE SET NULL;
+
+CREATE INDEX IF NOT EXISTS idx_project_policies_project_version
+    ON {{tables.project_policies}}(project_id, version DESC);
+CREATE INDEX IF NOT EXISTS idx_project_policies_created_by
+    ON {{tables.project_policies}}(created_by_workspace_id)
+    WHERE created_by_workspace_id IS NOT NULL;
+
+CREATE OR REPLACE FUNCTION {{schema}}.project_policies_update_timestamp()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = NOW();
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS project_policies_update_timestamp ON {{tables.project_policies}};
+CREATE TRIGGER project_policies_update_timestamp
+    BEFORE UPDATE ON {{tables.project_policies}}
+    FOR EACH ROW
+    EXECUTE FUNCTION {{schema}}.project_policies_update_timestamp();

beadhub/names.py

@@ -0,0 +1,33 @@
+"""Shared naming constants (e.g. classic workspace name prefixes)."""
+
+from __future__ import annotations
+
+# Classic names for alias generation (alice, bob, charlie, etc.)
+CLASSIC_NAMES = (
+    "alice",
+    "bob",
+    "charlie",
+    "dave",
+    "eve",
+    "frank",
+    "grace",
+    "henry",
+    "ivy",
+    "jack",
+    "kate",
+    "leo",
+    "mia",
+    "noah",
+    "olivia",
+    "peter",
+    "quinn",
+    "rose",
+    "sam",
+    "tara",
+    "uma",
+    "victor",
+    "wendy",
+    "xavier",
+    "yara",
+    "zoe",
+)