Upload 340 files

.env.example

@@ -1,4 +1,13 @@
 APP_NAME=MediaRouter
+APP_VERSION=1.0.0
+# Docker sets this to production. Local development keeps development so the
+# established SQLite workflow remains available.
+APP_ENVIRONMENT=development
+HOST=0.0.0.0
+PORT=7860
+# Comma-separated exact origins. Production requires at least one HTTPS origin
+# such as the separately hosted Vercel frontend; wildcard origins are rejected.
+CORS_ALLOWED_ORIGINS=http://localhost:3000
 TEMP_DIR=./temp
 OUTPUT_DIR=./outputs
 TEMPLATE_DIR=./app/templates/categories
@@ -17,6 +26,13 @@ FFMPEG_BINARY=ffmpeg
 FFPROBE_BINARY=ffprobe
 AUTH_ENABLED=true
 DATABASE_URL=sqlite+aiosqlite:///./data/mediarouter.db
+# SQLite initializes this schema locally. PostgreSQL must receive the SQL files
+# under app/security/migrations/ through your deployment migration process.
+SECURITY_AUTO_MIGRATE=false
+# PostgreSQL only: backend-only BYPASSRLS role used for authoritative users,
+# memberships, API-key principals, and canonical asset records.
+SECURITY_DATABASE_ROLE=mediarouter_security_service
+SECURITY_ENFORCE_RLS=true
 AUTH_ROLE_SCOPES={}
 AUTH_BOOTSTRAP_KEY_HASH=
 AUTH_BOOTSTRAP_KEY_PREFIX=
@@ -37,6 +53,14 @@ MCP_STDIO_API_KEY=
 SOCIAL_ENABLED=true
 # Example: postgresql+asyncpg://postgres:password@db.example:5432/postgres
 SOCIAL_DATABASE_URL=
+# Required for PostgreSQL production. This URL must authenticate as a normal
+# non-owner/non-BYPASSRLS API role. Do not use a Supabase service-role URL here.
+SOCIAL_TENANT_DATABASE_ROLE=mediarouter_tenant
+# Trusted backend-only worker connection. It must use the explicitly named
+# BYPASSRLS role and must never be exposed through REST, MCP, n8n, SDKs, or UI.
+SOCIAL_WORKER_DATABASE_URL=
+SOCIAL_WORKER_DATABASE_ROLE=mediarouter_social_worker
+SOCIAL_ENFORCE_RLS=true
 SOCIAL_AUTO_MIGRATE=false
 SOCIAL_WORKER_ENABLED=true
 SOCIAL_SCHEDULER_INTERVAL_SECONDS=30
@@ -53,6 +77,47 @@ SUPABASE_URL=
 SUPABASE_SERVICE_ROLE_KEY=
 SUPABASE_VAULT_ENABLED=false
 SOCIAL_OAUTH_REDIRECT_BASE_URL=
+
+# Provider-neutral generation runtime. WAN and FLUX are optional; neither is
+# enabled merely by the shared timeout/retry settings below.
+GENERATION_ENABLED=true
+GENERATION_JOB_RETRY_LIMIT=3
+# Shared remote AI worker client defaults. No worker is configured by these
+# values alone; do not add browser-visible worker URLs or credentials here.
+AI_WORKER_CONNECT_TIMEOUT_SECONDS=10
+AI_WORKER_REQUEST_TIMEOUT_SECONDS=60
+AI_WORKER_READ_TIMEOUT_SECONDS=300
+AI_WORKER_MAX_RETRIES=3
+AI_WORKER_RETRY_BACKOFF_SECONDS=0.5
+# Optional authenticated WAN 2.2 image-to-video worker. Set both values only
+# in backend/Hugging Face deployment secrets; never expose them to a browser,
+# MCP client, n8n node, SDK output, or logs. WAN stays unavailable if either
+# value is omitted or malformed, without blocking application startup.
+WAN_SPACE_URL=
+WAN_SPACE_TOKEN=
+# Optional authenticated FLUX.2 Klein image-generation worker. Set both
+# backend-only values in deployment secrets; never expose either value in a
+# browser, MCP/n8n request, SDK result, audit record, or log.
+FLUX_SPACE_URL=
+FLUX_SPACE_TOKEN=
+GENERATION_WORKER_ENABLED=true
+GENERATION_WORKER_INTERVAL_SECONDS=5
+GENERATION_WORKER_POLL_BACKOFF_SECONDS=2
+GENERATION_WORKER_BATCH_SIZE=8
+GENERATION_JOB_STALE_AFTER_SECONDS=900
+# Content Studio persistence/render limits. Editor state and render jobs are
+# durable PostgreSQL records; render workers use bounded temporary files only.
+EDITOR_STATE_MAX_BYTES=1048576
+RENDER_WORKER_ENABLED=true
+RENDER_WORKER_INTERVAL_SECONDS=2
+RENDER_JOB_STALE_AFTER_SECONDS=900
+RENDER_JOB_TIMEOUT_SECONDS=7200
+RENDER_JOB_RETRY_LIMIT=2
+RENDER_MAX_ACTIVE_JOBS_PER_PROJECT=1
+RENDER_MAX_TRACKS=32
+RENDER_MAX_CLIPS=500
+RENDER_MAX_DURATION_SECONDS=3600
+RENDER_MAX_INPUT_BYTES=4294967296
 GOOGLE_CLIENT_ID=
 GOOGLE_CLIENT_SECRET=
 # YouTube Data API v3 worker controls. Keep the client secret backend-only.
@@ -63,6 +128,11 @@ YOUTUBE_REQUEST_TIMEOUT_SECONDS=60
 YOUTUBE_PROCESSING_POLL_SECONDS=30
 META_CLIENT_ID=
 META_CLIENT_SECRET=
+# Preferred Meta application names. META_CLIENT_* remains a compatibility
+# alias for deployments created before this configuration contract.
+META_APP_ID=
+META_APP_SECRET=
+META_GRAPH_API_VERSION=v25.0
 TIKTOK_CLIENT_KEY=
 TIKTOK_CLIENT_SECRET=
 # Exact backend callback registered under TikTok Login Kit. It must be:

Dockerfile

@@ -6,9 +6,9 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
     PIP_DISABLE_PIP_VERSION_CHECK=1 \
     HF_HOME=/home/user/.cache/huggingface \
     APP_NAME=MediaRouter \
+    APP_ENVIRONMENT=production \
     TEMP_DIR=/app/temp \
     OUTPUT_DIR=/app/outputs \
-    DATABASE_URL=sqlite+aiosqlite:////app/data/mediarouter.db \
     PORT=7860
 
 RUN apt-get update \
@@ -39,6 +39,8 @@ USER user
 
 EXPOSE 7860
 
+STOPSIGNAL SIGTERM
+
 HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
     CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:7860/health', timeout=4)" || exit 1
 

README.md

@@ -57,6 +57,7 @@ media-api/
 ├── app/
 │   ├── api/              # versioned, thin FastAPI routes
 │   ├── core/             # settings, errors, logging, response models
+│   ├── generation/       # provider-neutral durable generation foundation
 │   ├── mcp/              # MCP server, registry, tools, resources, prompts
 │   ├── models/           # InputMedia and request/result models
 │   ├── operations/       # reusable FFmpeg operation functions
@@ -83,6 +84,19 @@ media-api/
 
 The top-level `api/`, `services/`, `operations/`, `workers/`, `core/`, and `models/` packages mirror the canonical `app/` modules as import-compatible entry points for integrations that use the requested layout. Runtime composition uses the single implementation under `app/`, so business logic is not duplicated.
 
+## Generation foundation
+
+MediaRouter includes a tenant-scoped generation request/job foundation at
+`/v1/generation`. Optional `wan` and `flux` providers implement audited WAN
+2.2 image-to-video and FLUX.2 Klein image-generation worker contracts. Each
+model stays unavailable until its backend-only URL/token are configured and
+live readiness verifies its exact worker identity. Requests use an idempotency
+key and may reference only canonical MediaRouter assets by opaque ID. See
+[`docs/generation-foundation.md`](docs/generation-foundation.md),
+[`docs/generation-wan.md`](docs/generation-wan.md), and
+[`docs/generation-flux.md`](docs/generation-flux.md) for the state machine,
+PostgreSQL migration, scopes, worker contracts, and security boundary.
+
 Each request creates `TEMP_DIR/<uuid>/{uploads,outputs,logs}`. Completed files are atomically moved to `OUTPUT_DIR/<uuid>` so they can be streamed. Both locations expire after `CLEANUP_MINUTES`; active requests are protected from the cleanup worker.
 
 ## Run locally
@@ -110,19 +124,29 @@ docker run --rm -p 7860:7860 --env-file .env media-api
 
 The image uses `python:3.10-slim`, installs FFmpeg, FFprobe, ImageMagick and the system libraries needed by CTranslate2/faster-whisper, clears apt and pip caches, runs as UID 1000, exposes port 7860, and includes a container health check.
 
+The Docker image sets `APP_ENVIRONMENT=production`. It intentionally has no
+SQLite database default: configure external PostgreSQL/Supabase, apply the
+explicit migrations, and set an exact Vercel CORS origin before startup. See
+[the production deployment gate](docs/production-deployment-gate.md).
+
 ## Deploy to Hugging Face Spaces
 
 1. Create a new Space and select **Docker** as the SDK.
 2. Push the contents of this directory to the Space repository. Keep the YAML block at the top of this README; `app_port` is already `7860`.
-3. Generate the initial administrator key locally with `python -m app.security.cli generate-bootstrap --environment live`. Store `API_KEY` in a password manager. Add only the printed `AUTH_BOOTSTRAP_KEY_HASH`, `AUTH_BOOTSTRAP_KEY_PREFIX`, and `AUTH_BOOTSTRAP_ENVIRONMENT` under **Settings → Secrets**. Do not commit them.
-4. Wait for the Docker build. The first Whisper call downloads the selected model to the Hugging Face cache. Persistent storage is optional, but avoids downloading models again after a cold rebuild.
-5. Check the public `https://<owner>-<space>.hf.space/health`, then use the saved key for every `/v1/*` or `/mcp/` request.
+3. Apply the PostgreSQL migrations in the documented dependency order, using a controlled administrative connection.
+4. Configure the required PostgreSQL/RLS/CORS variables and roles in Space Settings. Keep `SECURITY_AUTO_MIGRATE=false` and `SOCIAL_AUTO_MIGRATE=false`.
+5. Generate the initial administrator key locally with `python -m app.security.cli generate-bootstrap --environment live`. Store `API_KEY` in a password manager. Add only the printed `AUTH_BOOTSTRAP_KEY_HASH`, `AUTH_BOOTSTRAP_KEY_PREFIX`, and `AUTH_BOOTSTRAP_ENVIRONMENT` under **Settings → Secrets**. Do not commit them.
+6. Wait for the Docker build. The first Whisper call downloads the selected model to the Hugging Face cache. Persistent storage is optional for the model cache, but avoids downloading models again after a cold rebuild.
+7. Check the public `https://<owner>-<space>.hf.space/health`, then run `scripts/deployment_smoke.py` against the Space before accepting traffic.
 
 If using the supplied `media-api-huggingface.zip`, extract it first and push the extracted files so `Dockerfile` and this `README.md` are at the Space repository root. Do not commit the ZIP as the only repository file.
 
 Use one Uvicorn process in a CPU Space. FFmpeg and Whisper concurrency is managed in-process by `MAX_WORKERS`; multiple Uvicorn workers duplicate Whisper models and memory.
 
-For durable keys, audit records, and rate aggregates, attach Hugging Face persistent storage and set `DATABASE_URL=sqlite+aiosqlite:////data/mediarouter.db`. The default `./data/mediarouter.db` is appropriate locally but follows the Space filesystem lifecycle. The security layer uses SQLAlchemy so a future external database migration does not change authentication contracts; this release includes and supports the `aiosqlite` driver.
+Production keys, workspaces, projects, audit records, and rate aggregates live
+in external PostgreSQL/Supabase. SQLite remains a local-development and test
+backend only. Media files in `TEMP_DIR`/`OUTPUT_DIR` are expiring working data;
+see the deployment gate for their filesystem lifecycle.
 
 ## Connect the Vercel frontend to Hugging Face
 
@@ -155,13 +179,21 @@ The bootstrap fields are optional after the first successful start. If a Space f
 Recommended backend deployment settings are:
 
 ```env
+APP_ENVIRONMENT=production
 BASE_URL=https://basyx-mediarouter.hf.space
-DATABASE_URL=sqlite+aiosqlite:////data/mediarouter.db
+DATABASE_URL=postgresql+asyncpg://<security-role>:<password>@<host>/<database>
+SECURITY_DATABASE_ROLE=mediarouter_security_service
+SECURITY_ENFORCE_RLS=true
+SECURITY_AUTO_MIGRATE=false
+CORS_ALLOWED_ORIGINS=https://<your-vercel-project>.vercel.app
+SOCIAL_AUTO_MIGRATE=false
 AUTH_ROLE_SCOPES={}
 MCP_STDIO_API_KEY=<a-valid-mp_live-or-mp_test-key-if-stdio-MCP-is-enabled>
 ```
 
-`DATABASE_URL` uses `/data` so keys, audit logs, and rate-limit state survive only when Hugging Face persistent storage is attached. `BASE_URL` is the public Hugging Face origin, not the Vercel frontend URL.
+When social automation is enabled, configure its existing separate tenant and
+worker PostgreSQL URLs/roles as described in the deployment gate. `BASE_URL`
+is the public Hugging Face origin, not the Vercel frontend URL.
 
 ### Vercel environment variables
 
@@ -284,6 +316,7 @@ Scopes are enforced before route execution. Explicit scopes are combined with th
 | Jobs | `jobs:read`, `jobs:create`, `jobs:cancel` |
 | Assets | `assets:read`, `assets:write`, `assets:delete` |
 | MCP | `mcp:read`, `mcp:execute` |
+| Generation foundation | `generation:providers:read`, `generation:requests:read`, `generation:requests:create`, `generation:jobs:cancel` |
 | System | `system:read` |
 | Administration | `admin` |
 
@@ -1284,6 +1317,12 @@ curl -X POST https://your-space.hf.space/v1/social/posts \
 
 | Variable | Default | Purpose |
 |---|---:|---|
+| `APP_NAME` | `MediaRouter` | OpenAPI/application name |
+| `APP_VERSION` | `1.0.0` | Runtime and health version |
+| `APP_ENVIRONMENT` | `development` (`production` in Docker) | Enables fail-closed production configuration validation |
+| `HOST` | `0.0.0.0` | Documented bind host; Docker command binds explicitly to this address |
+| `PORT` | `7860` | Hugging Face application port |
+| `CORS_ALLOWED_ORIGINS` | empty | Comma-separated exact frontend origins; production requires HTTPS and rejects wildcard CORS |
 | `TEMP_DIR` | `./temp` | Request workspaces and in-progress files |
 | `OUTPUT_DIR` | `./outputs` | Published files served by download URLs |
 | `TEMPLATE_DIR` | built-in `app/templates/categories` | Recursively scanned YAML workflow catalog |
@@ -1301,7 +1340,10 @@ curl -X POST https://your-space.hf.space/v1/social/posts \
 | `FFMPEG_BINARY` | `ffmpeg` | FFmpeg executable name/path |
 | `FFPROBE_BINARY` | `ffprobe` | FFprobe executable name/path |
 | `AUTH_ENABLED` | `true` | Fail-closed API-key enforcement; disable only for isolated development/tests |
-| `DATABASE_URL` | `sqlite+aiosqlite:///./data/mediarouter.db` | Hash-only keys, audit records, and rate aggregates |
+| `DATABASE_URL` | `sqlite+aiosqlite:///./data/mediarouter.db` | Backend-only security/tenant/asset store; bare `postgresql://` is normalized to `postgresql+asyncpg://` |
+| `SECURITY_AUTO_MIGRATE` | `false` | Permit metadata creation for controlled local/testing use; PostgreSQL production must apply `app/security/migrations/` |
+| `SECURITY_DATABASE_ROLE` | empty | Required with PostgreSQL RLS; backend-only role for authoritative tenancy and canonical asset administration |
+| `SECURITY_ENFORCE_RLS` | `true` | Fail startup if the security-store role cannot administer its forced-RLS tables |
 | `AUTH_ROLE_SCOPES` | `{}` | JSON custom role-to-scope mappings |
 | `AUTH_BOOTSTRAP_KEY_HASH` | empty | SHA-256 hash for first-start administrator |
 | `AUTH_BOOTSTRAP_KEY_PREFIX` | empty | Safe display prefix matching the bootstrap key |
@@ -1314,8 +1356,28 @@ curl -X POST https://your-space.hf.space/v1/social/posts \
 | `AUTH_DEFAULT_PROCESSING_BYTES_PER_DAY` | `107374182400` | Default daily uploaded processing bytes |
 | `AUTH_TRUST_PROXY_HEADERS` | `true` | Use first `X-Forwarded-For` address for audits behind HF/Vercel |
 | `MCP_STDIO_API_KEY` | empty | Existing API key required by authenticated standalone stdio MCP |
+| `GENERATION_ENABLED` | `true` | Enable the additive durable generation domain; it does not configure a model by itself |
+| `GENERATION_JOB_RETRY_LIMIT` | `3` | Bounded durable submission retry count; the initial submission is separate |
+| `AI_WORKER_CONNECT_TIMEOUT_SECONDS` | `10` | Remote generation-worker connection timeout |
+| `AI_WORKER_REQUEST_TIMEOUT_SECONDS` | `60` | Remote generation-worker request/write timeout |
+| `AI_WORKER_READ_TIMEOUT_SECONDS` | `300` | Remote generation-worker response/read timeout |
+| `AI_WORKER_MAX_RETRIES` | `3` | Bounded transport retries for safe idempotent worker operations |
+| `AI_WORKER_RETRY_BACKOFF_SECONDS` | `0.5` | Base exponential backoff for worker transport retries |
+| `WAN_SPACE_URL` | empty | Trusted backend-only WAN worker origin; requires `WAN_SPACE_TOKEN` and is never client-selectable |
+| `WAN_SPACE_TOKEN` | empty | Backend-only Bearer token for the WAN worker; never return, log, or store in browser/MCP/n8n/SDK output |
+| `FLUX_SPACE_URL` | empty | Trusted backend-only FLUX worker origin; requires `FLUX_SPACE_TOKEN` and is never client-selectable |
+| `FLUX_SPACE_TOKEN` | empty | Backend-only Bearer token for FLUX; never return, log, or store in browser/MCP/n8n/SDK output |
+| `GENERATION_WORKER_ENABLED` | `true` | Run durable generation dispatch, polling, and output-ingestion worker |
+| `GENERATION_WORKER_INTERVAL_SECONDS` | `5` | Generation worker dispatch/reconciliation interval |
+| `GENERATION_WORKER_POLL_BACKOFF_SECONDS` | `2` | Base bounded reconciliation poll backoff after a transient worker error |
+| `GENERATION_WORKER_BATCH_SIZE` | `8` | Maximum generation jobs claimed per dispatch/reconciliation cycle |
+| `GENERATION_JOB_STALE_AFTER_SECONDS` | `900` | Submission ambiguity threshold and durable reconciliation lease duration |
 | `SOCIAL_ENABLED` | `true` | Enable the additive social domain; existing media APIs remain independent |
 | `SOCIAL_DATABASE_URL` | `DATABASE_URL` | Async SQLAlchemy URL; use Supabase/Postgres in production |
+| `SOCIAL_TENANT_DATABASE_ROLE` | empty | Required with PostgreSQL RLS; non-owner/non-`BYPASSRLS` role for API tenant sessions |
+| `SOCIAL_WORKER_DATABASE_URL` | empty | Backend-only trusted worker connection; required for PostgreSQL scheduler/Vault usage |
+| `SOCIAL_WORKER_DATABASE_ROLE` | empty | Expected `BYPASSRLS` role for the worker URL; checked at social startup |
+| `SOCIAL_ENFORCE_RLS` | `true` | Fail startup if PostgreSQL API/worker role separation cannot be verified |
 | `SOCIAL_AUTO_MIGRATE` | `false` | Local/test metadata creation only; never use for production migration management |
 | `SOCIAL_WORKER_ENABLED` | `true` | Run durable scheduler/publisher claim loop when schema is ready |
 | `SOCIAL_SCHEDULER_INTERVAL_SECONDS` | `30` | Scheduler polling interval |

app/ai/__init__.py

@@ -0,0 +1 @@
+"""Provider-neutral AI Studio application boundary."""

app/ai/api.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Header, Path, Query, Request, status
+
+from app.ai.schemas import AiCapabilities, AiGenerationRequest, AiHistory, AiJob
+from app.security.errors import ForbiddenError
+
+router = APIRouter(prefix="/v1/ai", tags=["ai"])
+
+
+def _identity(request: Request) -> tuple[str, str, str | None, str]:
+    context = request.state.auth
+    if not context.workspace_id or not context.user_id:
+        raise ForbiddenError
+    return (
+        context.workspace_id,
+        context.user_id,
+        context.api_key_id,
+        request.state.request_id,
+    )
+
+
+@router.get("/capabilities", response_model=AiCapabilities)
+async def capabilities(request: Request) -> AiCapabilities:
+    return request.app.state.container.ai.capabilities()
+
+
+@router.get("/jobs", response_model=AiHistory)
+async def list_jobs(
+    request: Request,
+    offset: Annotated[int, Query(ge=0)] = 0,
+    limit: Annotated[int, Query(ge=1, le=100)] = 25,
+) -> AiHistory:
+    workspace_id, user_id, _, _ = _identity(request)
+    return await request.app.state.container.ai.history(
+        workspace_id=workspace_id,
+        user_id=user_id,
+        offset=offset,
+        limit=limit,
+    )
+
+
+@router.post("/jobs", response_model=AiJob, status_code=status.HTTP_202_ACCEPTED)
+async def create_job(
+    request: Request,
+    payload: AiGenerationRequest,
+    idempotency_key: Annotated[str, Header(alias="Idempotency-Key", min_length=8, max_length=255)],
+) -> AiJob:
+    workspace_id, user_id, api_key_id, request_id = _identity(request)
+    return await request.app.state.container.ai.create(
+        workspace_id=workspace_id,
+        user_id=user_id,
+        api_key_id=api_key_id,
+        request_id=request_id,
+        payload=payload,
+        idempotency_key=idempotency_key,
+    )
+
+
+@router.get("/jobs/{generation_id}", response_model=AiJob)
+async def get_job(
+    request: Request,
+    generation_id: Annotated[str, Path(min_length=36, max_length=36)],
+) -> AiJob:
+    workspace_id, user_id, _, _ = _identity(request)
+    return await request.app.state.container.ai.get(
+        workspace_id=workspace_id,
+        user_id=user_id,
+        generation_id=generation_id,
+    )
+
+
+@router.post("/jobs/{generation_id}/cancel", response_model=AiJob)
+async def cancel_job(
+    request: Request,
+    generation_id: Annotated[str, Path(min_length=36, max_length=36)],
+) -> AiJob:
+    workspace_id, user_id, api_key_id, request_id = _identity(request)
+    return await request.app.state.container.ai.cancel(
+        workspace_id=workspace_id,
+        user_id=user_id,
+        api_key_id=api_key_id,
+        request_id=request_id,
+        generation_id=generation_id,
+    )

app/ai/schemas.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated, Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+AiCategory = Literal["generate", "transform", "understand", "create"]
+AiOperation = Literal["generate_image", "generate_video"]
+AiJobStatus = Literal[
+    "queued", "processing", "retrying", "completed", "failed", "cancelling", "cancelled"
+]
+
+
+class AiModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    display_name: str
+    operation: AiOperation
+    input_types: list[str]
+    output_types: list[str]
+    input_schema: dict[str, object] = Field(default_factory=dict)
+    available: bool
+    provider_display_name: str
+    pricing: None = None
+
+
+class AiTool(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    category: AiCategory
+    operation: AiOperation
+    name: str
+    description: str
+    input_types: list[str]
+    output_types: list[str]
+    required_permission: str
+    job_type: str = "generation"
+    supports_project_context: bool = True
+    supports_asset_input: bool
+    supports_prompt_input: bool = True
+    supports_multiple_inputs: bool = False
+    supports_batch: bool = False
+    available: bool
+    models: list[AiModel] = Field(default_factory=list)
+
+
+class AiProvider(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    display_name: str
+    available: bool
+    operations: list[AiOperation] = Field(default_factory=list)
+    supports_cancellation: bool = False
+
+
+class AiCapabilities(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    available: bool
+    categories: list[AiCategory]
+    tools: list[AiTool]
+    providers: list[AiProvider]
+    permissions: list[str]
+    feature_flag: str = "ai"
+
+
+class AiOutputPreferences(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    attach_to_project: bool = True
+
+
+class AiImageParameters(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    mode: Literal["fast", "quality"] = "fast"
+    seed: int = Field(default=42, ge=0, le=2_147_483_647)
+    randomize_seed: bool = False
+    width: int = Field(default=1024, ge=256, le=1024, multiple_of=8)
+    height: int = Field(default=1024, ge=256, le=1024, multiple_of=8)
+    steps: int = Field(default=4, ge=1, le=100)
+    guidance: float = Field(default=1.0, ge=0.0, le=10.0)
+    enhance_prompt: bool = False
+
+
+class AiVideoParameters(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    negative_prompt: str | None = Field(default=None, max_length=4_000)
+    duration_seconds: float = Field(default=5.0, ge=0.5, le=5.0)
+    steps: int = Field(default=4, ge=1, le=30)
+    guidance: float = Field(default=1.0, ge=0.0, le=10.0)
+    secondary_guidance: float = Field(default=1.0, ge=0.0, le=10.0)
+    seed: int = Field(default=42, ge=0, le=2_147_483_647)
+    randomize_seed: bool = False
+
+
+class AiGenerateImageRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    operation: Literal["generate_image"]
+    prompt: str = Field(min_length=1, max_length=4_000)
+    model: str | None = Field(default=None, min_length=1, max_length=255)
+    project_id: UUID | None = None
+    source_asset_ids: list[UUID] = Field(default_factory=list, max_length=1)
+    parameters: AiImageParameters = Field(default_factory=AiImageParameters)
+    output_preferences: AiOutputPreferences = Field(default_factory=AiOutputPreferences)
+
+
+class AiGenerateVideoRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    operation: Literal["generate_video"]
+    prompt: str = Field(min_length=1, max_length=4_000)
+    model: str | None = Field(default=None, min_length=1, max_length=255)
+    project_id: UUID | None = None
+    source_asset_ids: list[UUID] = Field(min_length=1, max_length=1)
+    parameters: AiVideoParameters = Field(default_factory=AiVideoParameters)
+    output_preferences: AiOutputPreferences = Field(default_factory=AiOutputPreferences)
+
+
+AiGenerationRequest = Annotated[
+    AiGenerateImageRequest | AiGenerateVideoRequest,
+    Field(discriminator="operation"),
+]
+
+
+class AiOutput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    asset_id: str
+    media_type: Literal["image", "video"]
+
+
+class AiJob(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    generation_id: str
+    operation: AiOperation
+    status: AiJobStatus
+    prompt: str
+    project_id: str | None = None
+    source_asset_id: str | None = None
+    output: AiOutput | None = None
+    model: str
+    provider_display_name: str
+    progress: None = None
+    error_code: str | None = None
+    error_message: str | None = None
+    retryable: bool = False
+    usage: None = None
+    estimated_cost: None = None
+    actual_cost: None = None
+    created_at: datetime
+    updated_at: datetime
+    completed_at: datetime | None = None
+
+
+class AiHistory(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    items: list[AiJob]
+    offset: int
+    limit: int

app/ai/service.py

@@ -0,0 +1,378 @@
+from __future__ import annotations
+
+from app.ai.schemas import (
+    AiCapabilities,
+    AiGenerateImageRequest,
+    AiGenerateVideoRequest,
+    AiGenerationRequest,
+    AiHistory,
+    AiJob,
+    AiModel,
+    AiOutput,
+    AiProvider,
+    AiTool,
+)
+from app.generation.domain.enums import (
+    GenerationModality,
+    GenerationRequestStatus,
+)
+from app.generation.domain.errors import (
+    GenerationCapabilityUnsupportedError,
+    GenerationValidationError,
+)
+from app.generation.model_registry import GenerationModelView
+from app.generation.schemas.requests import (
+    FluxGenerationOptions,
+    GenerationRequestCreate,
+    GenerationRequestView,
+    WanGenerationOptions,
+)
+from app.generation.services.generation_service import GenerationService
+from app.projects.schemas import ProjectStatus
+from app.projects.services.project_service import ProjectService
+from app.security.assets import CanonicalAssetNotFoundError, CanonicalAssetService
+from app.security.audit import AuditService
+
+
+_OPERATION_MODALITY = {
+    "generate_image": GenerationModality.IMAGE,
+    "generate_video": GenerationModality.VIDEO,
+}
+
+
+class AiStudioService:
+    """Capability-driven facade over the existing durable generation domain."""
+
+    def __init__(
+        self,
+        generation: GenerationService,
+        projects: ProjectService,
+        assets: CanonicalAssetService,
+        audit: AuditService,
+    ) -> None:
+        self.generation = generation
+        self.projects = projects
+        self.assets = assets
+        self.audit = audit
+
+    def capabilities(self) -> AiCapabilities:
+        models = self.generation.models.list()
+        tools = [
+            self._tool(
+                operation="generate_image",
+                name="Generate Image",
+                description="Create or transform a canonical image with an available image model.",
+                models=[item for item in models if item.model.modality is GenerationModality.IMAGE],
+                input_types=["text", "image"],
+                output_types=["image"],
+            ),
+            self._tool(
+                operation="generate_video",
+                name="Generate Video",
+                description="Create a video from a canonical project image.",
+                models=[item for item in models if item.model.modality is GenerationModality.VIDEO],
+                input_types=["text", "image"],
+                output_types=["video"],
+            ),
+        ]
+        providers = []
+        for adapter in self.generation.providers.list():
+            provider_models = [item for item in models if item.provider_id == adapter.provider]
+            operations = sorted({self._operation_for_model(item) for item in provider_models})
+            providers.append(
+                AiProvider(
+                    id=adapter.provider,
+                    display_name=adapter.capabilities.name,
+                    available=bool(
+                        self.generation.ready
+                        and adapter.available
+                        and any(item.available for item in provider_models)
+                    ),
+                    operations=operations,
+                    supports_cancellation=adapter.capabilities.supports_cancellation,
+                )
+            )
+        return AiCapabilities(
+            available=any(tool.available for tool in tools),
+            categories=["generate"],
+            tools=tools,
+            providers=providers,
+            permissions=[
+                "ai:read",
+                "ai:generate",
+                "ai:transform",
+                "ai:analyze",
+                "ai:create",
+            ],
+        )
+
+    async def create(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str | None,
+        request_id: str,
+        payload: AiGenerationRequest,
+        idempotency_key: str,
+    ) -> AiJob:
+        project_id = str(payload.project_id) if payload.project_id else None
+        source_asset_id = str(payload.source_asset_ids[0]) if payload.source_asset_ids else None
+        if payload.project_id is not None:
+            project = await self.projects.get(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                project_id=project_id or "",
+            )
+            if project.status is not ProjectStatus.ACTIVE:
+                raise GenerationValidationError("AI jobs require an active project.")
+        if source_asset_id is not None:
+            try:
+                asset = await self.assets.get_owned_by_id(
+                    workspace_id=workspace_id,
+                    user_id=user_id,
+                    asset_id=source_asset_id,
+                )
+            except CanonicalAssetNotFoundError as exc:
+                raise GenerationValidationError(
+                    "AI source asset was not found in this workspace."
+                ) from exc
+            if project_id is not None and asset.project_id != project_id:
+                raise GenerationValidationError(
+                    "AI source asset must belong to the selected project."
+                )
+        model = self._select_model(payload.operation, payload.model)
+        request = self._generation_request(payload, model)
+        created = await self.generation.create(
+            workspace_id=workspace_id,
+            user_id=user_id,
+            payload=request,
+            idempotency_key=idempotency_key,
+            project_id=(project_id if payload.output_preferences.attach_to_project else None),
+            product_surface="ai_studio",
+        )
+        await self.audit.record_event(
+            workspace_id=workspace_id,
+            user_id=user_id,
+            api_key_id=api_key_id,
+            request_id=request_id,
+            event_type="ai.generation_requested",
+            entity_type="generation_job",
+            entity_id=created.job.id,
+            metadata={
+                "operation": payload.operation,
+                "model": created.model_id,
+                "project_id": project_id,
+            },
+        )
+        return self._job(created)
+
+    async def history(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        offset: int,
+        limit: int,
+    ) -> AiHistory:
+        items = await self.generation.list_requests(
+            workspace_id,
+            user_id,
+            offset=offset,
+            limit=limit,
+            product_surface="ai_studio",
+        )
+        return AiHistory(
+            items=[self._job(item) for item in items],
+            offset=offset,
+            limit=limit,
+        )
+
+    async def get(self, *, workspace_id: str, user_id: str, generation_id: str) -> AiJob:
+        request = await self.generation.get_request(workspace_id, user_id, generation_id)
+        if request.product_surface != "ai_studio":
+            raise GenerationValidationError("AI generation was not found.")
+        return self._job(request)
+
+    async def cancel(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str | None,
+        request_id: str,
+        generation_id: str,
+    ) -> AiJob:
+        request = await self.generation.get_request(workspace_id, user_id, generation_id)
+        if request.product_surface != "ai_studio":
+            raise GenerationValidationError("AI generation was not found.")
+        await self.generation.cancel(workspace_id, user_id, request.job.id)
+        updated = await self.generation.get_request(workspace_id, user_id, generation_id)
+        if updated.status is GenerationRequestStatus.CANCELLED:
+            await self.audit.record_event(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                api_key_id=api_key_id,
+                request_id=request_id,
+                event_type="ai.generation_cancelled",
+                entity_type="generation_job",
+                entity_id=request.job.id,
+                metadata={"operation": self._operation_for_request(request)},
+            )
+        return self._job(updated)
+
+    def _select_model(self, operation: str, requested_model: str | None) -> GenerationModelView:
+        modality = _OPERATION_MODALITY[operation]
+        matches = [
+            model
+            for model in self.generation.models.list()
+            if model.model.modality is modality
+            and model.available
+            and (requested_model is None or model.model.id == requested_model)
+        ]
+        if not matches:
+            raise GenerationCapabilityUnsupportedError(
+                "No ready model supports the requested AI operation."
+            )
+        if requested_model is not None and len(matches) != 1:
+            raise GenerationCapabilityUnsupportedError("The requested AI model is not available.")
+        return sorted(matches, key=lambda item: (item.provider_id, item.model.id))[0]
+
+    @staticmethod
+    def _generation_request(
+        payload: AiGenerationRequest, model: GenerationModelView
+    ) -> GenerationRequestCreate:
+        source_asset_id = str(payload.source_asset_ids[0]) if payload.source_asset_ids else None
+        if isinstance(payload, AiGenerateImageRequest):
+            options = payload.parameters
+            return GenerationRequestCreate(
+                provider=model.provider_id,
+                model_id=model.model.id,
+                modality=GenerationModality.IMAGE,
+                prompt=payload.prompt,
+                input_asset_id=source_asset_id,
+                flux=FluxGenerationOptions(
+                    mode_choice=(
+                        "Base (50 steps)" if options.mode == "quality" else "Distilled (4 steps)"
+                    ),
+                    seed=options.seed,
+                    randomize_seed=options.randomize_seed,
+                    width=options.width,
+                    height=options.height,
+                    num_inference_steps=options.steps,
+                    guidance_scale=options.guidance,
+                    prompt_upsampling=options.enhance_prompt,
+                ),
+            )
+        if isinstance(payload, AiGenerateVideoRequest):
+            options = payload.parameters
+            return GenerationRequestCreate(
+                provider=model.provider_id,
+                model_id=model.model.id,
+                modality=GenerationModality.VIDEO,
+                prompt=payload.prompt,
+                input_asset_id=source_asset_id,
+                wan=WanGenerationOptions(
+                    negative_prompt=options.negative_prompt,
+                    duration_seconds=options.duration_seconds,
+                    steps=options.steps,
+                    guidance_scale=options.guidance,
+                    guidance_scale_2=options.secondary_guidance,
+                    seed=options.seed,
+                    randomize_seed=options.randomize_seed,
+                ),
+            )
+        raise GenerationCapabilityUnsupportedError("AI operation is unsupported.")
+
+    def _tool(
+        self,
+        *,
+        operation: str,
+        name: str,
+        description: str,
+        models: list[GenerationModelView],
+        input_types: list[str],
+        output_types: list[str],
+    ) -> AiTool:
+        public_models = [self._model(item, operation) for item in models]
+        return AiTool(
+            id=operation.replace("_", "-"),
+            category="generate",
+            operation=operation,
+            name=name,
+            description=description,
+            input_types=input_types,
+            output_types=output_types,
+            required_permission="ai:generate",
+            supports_asset_input=any(item.model.input_asset_supported for item in models),
+            available=any(item.available and self.generation.ready for item in models),
+            models=public_models,
+        )
+
+    def _model(self, item: GenerationModelView, operation: str) -> AiModel:
+        provider = self.generation.providers.get(item.provider_id)
+        return AiModel(
+            id=item.model.id,
+            display_name=item.model.name,
+            operation=operation,
+            input_types=(["text", "image"] if item.model.input_asset_supported else ["text"]),
+            output_types=[item.model.modality.value],
+            input_schema=dict(item.model.input_schema),
+            available=bool(self.generation.ready and item.available),
+            provider_display_name=provider.capabilities.name,
+        )
+
+    @staticmethod
+    def _operation_for_model(item: GenerationModelView) -> str:
+        return (
+            "generate_image"
+            if item.model.modality is GenerationModality.IMAGE
+            else "generate_video"
+        )
+
+    @staticmethod
+    def _operation_for_request(item: GenerationRequestView) -> str:
+        return "generate_image" if item.modality is GenerationModality.IMAGE else "generate_video"
+
+    def _job(self, item: GenerationRequestView) -> AiJob:
+        operation = self._operation_for_request(item)
+        status_map = {
+            GenerationRequestStatus.QUEUED: "queued",
+            GenerationRequestStatus.SUBMITTING: "processing",
+            GenerationRequestStatus.RUNNING: "processing",
+            GenerationRequestStatus.RETRYING: "retrying",
+            GenerationRequestStatus.SUCCEEDED: "completed",
+            GenerationRequestStatus.FAILED: "failed",
+            GenerationRequestStatus.CANCEL_REQUESTED: "cancelling",
+            GenerationRequestStatus.CANCELLED: "cancelled",
+        }
+        provider = self.generation.providers.get(item.provider)
+        output = None
+        if item.job.output_asset_id and item.status is GenerationRequestStatus.SUCCEEDED:
+            output = AiOutput(
+                asset_id=item.job.output_asset_id,
+                media_type=("image" if item.modality is GenerationModality.IMAGE else "video"),
+            )
+        retryable_codes = {
+            "GENERATION_MODEL_UNAVAILABLE",
+            "GENERATION_SUBMISSION_RETRYING",
+            "GENERATION_PROVIDER_STATUS_FAILED",
+        }
+        return AiJob(
+            id=item.job.id,
+            generation_id=item.id,
+            operation=operation,
+            status=status_map[item.status],
+            prompt=item.prompt,
+            project_id=item.project_id,
+            source_asset_id=item.input_asset_id,
+            output=output,
+            model=item.model_id,
+            provider_display_name=provider.capabilities.name,
+            error_code=item.job.error_code,
+            error_message=item.job.error_message,
+            retryable=item.job.error_code in retryable_codes,
+            created_at=item.created_at,
+            updated_at=item.updated_at,
+            completed_at=item.completed_at,
+        )

app/analytics/__init__.py

@@ -0,0 +1 @@
+"""Workspace analytics domain built on authoritative Social provider data."""

app/analytics/api.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Header, Query, Request, status
+
+from app.analytics.schemas import (
+    AnalyticsCapabilities,
+    AnalyticsOverview,
+    AnalyticsPostList,
+    AnalyticsQuery,
+    AnalyticsSyncList,
+    AnalyticsSyncRequest,
+    AnalyticsSyncRunView,
+    AnalyticsTimeseries,
+)
+
+router = APIRouter(prefix="/v1/analytics", tags=["analytics"])
+
+
+def _identity(request: Request) -> tuple[str, str]:
+    context = request.state.auth
+    if not context.workspace_id or not context.user_id:
+        from fastapi import HTTPException
+
+        raise HTTPException(status_code=403, detail="No active workspace membership.")
+    return context.workspace_id, context.user_id
+
+
+def _service(request: Request):
+    service = request.app.state.container.analytics
+    service.ensure_ready()
+    return service
+
+
+@router.get("/capabilities", response_model=list[AnalyticsCapabilities])
+async def capabilities(request: Request) -> list[AnalyticsCapabilities]:
+    return await _service(request).capabilities()
+
+
+@router.get("/overview", response_model=AnalyticsOverview)
+async def overview(
+    request: Request, query: Annotated[AnalyticsQuery, Depends()]
+) -> AnalyticsOverview:
+    workspace_id, _ = _identity(request)
+    return await _service(request).overview(workspace_id, query)
+
+
+@router.get("/timeseries", response_model=AnalyticsTimeseries)
+async def timeseries(
+    request: Request, query: Annotated[AnalyticsQuery, Depends()]
+) -> AnalyticsTimeseries:
+    workspace_id, _ = _identity(request)
+    return await _service(request).timeseries(workspace_id, query)
+
+
+@router.get("/platforms", response_model=AnalyticsOverview)
+async def platforms(
+    request: Request, query: Annotated[AnalyticsQuery, Depends()]
+) -> AnalyticsOverview:
+    workspace_id, _ = _identity(request)
+    return await _service(request).overview(workspace_id, query)
+
+
+@router.get("/platforms/{provider}", response_model=AnalyticsOverview)
+async def platform(
+    request: Request,
+    provider: str,
+    query: Annotated[AnalyticsQuery, Depends()],
+) -> AnalyticsOverview:
+    workspace_id, _ = _identity(request)
+    query.provider = provider
+    return await _service(request).overview(workspace_id, query)
+
+
+@router.get("/posts", response_model=AnalyticsPostList)
+async def posts(request: Request, query: Annotated[AnalyticsQuery, Depends()]) -> AnalyticsPostList:
+    workspace_id, _ = _identity(request)
+    return await _service(request).posts(workspace_id, query)
+
+
+@router.get("/posts/{post_id}", response_model=AnalyticsPostList)
+async def post(
+    request: Request,
+    post_id: str,
+    query: Annotated[AnalyticsQuery, Depends()],
+) -> AnalyticsPostList:
+    workspace_id, _ = _identity(request)
+    return await _service(request).post(workspace_id, post_id, query)
+
+
+@router.get("/projects/{project_id}", response_model=AnalyticsOverview)
+async def project(
+    request: Request,
+    project_id: str,
+    query: Annotated[AnalyticsQuery, Depends()],
+) -> AnalyticsOverview:
+    workspace_id, user_id = _identity(request)
+    await request.app.state.container.projects.get(
+        workspace_id=workspace_id, user_id=user_id, project_id=project_id
+    )
+    query.project_id = project_id
+    return await _service(request).overview(workspace_id, query)
+
+
+@router.get("/sync-runs", response_model=AnalyticsSyncList)
+async def sync_runs(
+    request: Request,
+    offset: int = Query(default=0, ge=0, le=100_000),
+    limit: int = Query(default=50, ge=1, le=500),
+) -> AnalyticsSyncList:
+    workspace_id, _ = _identity(request)
+    items = await _service(request).repository.list_syncs(workspace_id, offset=offset, limit=limit)
+    return AnalyticsSyncList(
+        items=[_service(request)._sync_view(item) for item in items],
+        offset=offset,
+        limit=limit,
+    )
+
+
+@router.get("/sync-runs/{run_id}", response_model=AnalyticsSyncRunView)
+async def sync_run(request: Request, run_id: str) -> AnalyticsSyncRunView:
+    workspace_id, _ = _identity(request)
+    return _service(request)._sync_view(
+        await _service(request).repository.get_sync(workspace_id, run_id)
+    )
+
+
+@router.post("/sync-runs/{run_id}/cancel", response_model=AnalyticsSyncRunView)
+async def cancel_sync(request: Request, run_id: str) -> AnalyticsSyncRunView:
+    workspace_id, _ = _identity(request)
+    run = await _service(request).repository.cancel_sync(workspace_id, run_id)
+    await _service(request).audit.record(
+        workspace_id=workspace_id,
+        event_type="analytics.sync_cancelled",
+        metadata={"sync_run_id": run.id},
+        api_key_id=request.state.auth.api_key_id,
+        request_id=request.state.request_id,
+    )
+    return _service(request)._sync_view(run)
+
+
+@router.post("/sync", response_model=AnalyticsSyncRunView, status_code=status.HTTP_202_ACCEPTED)
+async def sync(
+    request: Request,
+    payload: AnalyticsSyncRequest,
+    idempotency_key: str | None = Header(default=None, alias="Idempotency-Key"),
+) -> AnalyticsSyncRunView:
+    workspace_id, user_id = _identity(request)
+    if idempotency_key:
+        payload.idempotency_key = idempotency_key
+    return await _service(request).create_sync(workspace_id, user_id, payload)

app/analytics/errors.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from app.core.exceptions import MediaAPIError
+
+
+class AnalyticsValidationError(MediaAPIError):
+    code = "ANALYTICS_VALIDATION_ERROR"
+    status_code = 422
+
+
+class AnalyticsNotFoundError(MediaAPIError):
+    code = "ANALYTICS_NOT_FOUND"
+    status_code = 404
+
+
+class AnalyticsIdempotencyConflictError(MediaAPIError):
+    code = "ANALYTICS_IDEMPOTENCY_CONFLICT"
+    status_code = 409

app/analytics/models.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from uuid import uuid4
+
+from sqlalchemy import (
+    JSON,
+    DateTime,
+    Float,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.social.models import SocialBase
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def new_id() -> str:
+    return str(uuid4())
+
+
+class AnalyticsSyncRun(SocialBase):
+    __tablename__ = "analytics_sync_runs"
+    __table_args__ = (
+        UniqueConstraint(
+            "workspace_id", "idempotency_key", name="uq_analytics_sync_workspace_idempotency"
+        ),
+        Index("ix_analytics_sync_workspace_status", "workspace_id", "status"),
+        Index("ix_analytics_sync_due", "status", "next_attempt_at"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    workspace_id: Mapped[str] = mapped_column(String(120), nullable=False)
+    project_id: Mapped[str | None] = mapped_column(String(36))
+    provider: Mapped[str | None] = mapped_column(String(32))
+    date_from: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    date_to: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    timezone: Mapped[str] = mapped_column(String(100), nullable=False)
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="queued")
+    idempotency_key: Mapped[str] = mapped_column(String(255), nullable=False)
+    requested_by: Mapped[str | None] = mapped_column(String(120))
+    attempt_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    next_attempt_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    error_code: Mapped[str | None] = mapped_column(String(100))
+    error_message: Mapped[str | None] = mapped_column(Text)
+    metrics_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=utcnow
+    )
+    started_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow
+    )
+
+
+class AnalyticsMetricSnapshot(SocialBase):
+    __tablename__ = "analytics_metric_snapshots"
+    __table_args__ = (
+        UniqueConstraint(
+            "workspace_id",
+            "provider",
+            "external_object_id",
+            "metric_name",
+            "bucket_start",
+            name="uq_analytics_metric_snapshot",
+        ),
+        Index("ix_analytics_metric_snapshots_workspace_bucket", "workspace_id", "bucket_start"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    workspace_id: Mapped[str] = mapped_column(String(120), nullable=False)
+    project_id: Mapped[str | None] = mapped_column(String(36))
+    social_post_id: Mapped[str | None] = mapped_column(
+        String(36), ForeignKey("social_posts.id", ondelete="CASCADE")
+    )
+    social_account_id: Mapped[str | None] = mapped_column(
+        String(36), ForeignKey("social_accounts.id", ondelete="CASCADE")
+    )
+    provider: Mapped[str] = mapped_column(String(32), nullable=False)
+    external_object_id: Mapped[str] = mapped_column(String(255), nullable=False)
+    metric_name: Mapped[str] = mapped_column(String(64), nullable=False)
+    metric_value: Mapped[float] = mapped_column(Float, nullable=False)
+    bucket_start: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    dimensions: Mapped[dict[str, object]] = mapped_column(JSON, nullable=False, default=dict)
+    source: Mapped[str] = mapped_column(String(64), nullable=False, default="provider")
+    collected_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=utcnow
+    )
+    provider_updated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class AnalyticsPostMetric(SocialBase):
+    __tablename__ = "analytics_post_metrics"
+    __table_args__ = (
+        UniqueConstraint(
+            "workspace_id",
+            "social_post_target_id",
+            "metric_date",
+            name="uq_analytics_post_metric_bucket",
+        ),
+        Index("ix_analytics_post_metrics_workspace_date", "workspace_id", "metric_date"),
+        Index(
+            "ix_analytics_post_metrics_project_date", "workspace_id", "project_id", "metric_date"
+        ),
+        Index("ix_analytics_post_metrics_provider_date", "workspace_id", "provider", "metric_date"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    workspace_id: Mapped[str] = mapped_column(String(120), nullable=False)
+    project_id: Mapped[str | None] = mapped_column(String(36))
+    social_post_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("social_posts.id", ondelete="CASCADE"), nullable=False
+    )
+    social_post_target_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("social_post_targets.id", ondelete="CASCADE"), nullable=False
+    )
+    social_account_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("social_accounts.id", ondelete="CASCADE"), nullable=False
+    )
+    provider: Mapped[str] = mapped_column(String(32), nullable=False)
+    external_post_id: Mapped[str | None] = mapped_column(String(255))
+    metric_date: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    views: Mapped[int | None] = mapped_column()
+    impressions: Mapped[int | None] = mapped_column()
+    likes: Mapped[int | None] = mapped_column()
+    comments: Mapped[int | None] = mapped_column()
+    shares: Mapped[int | None] = mapped_column()
+    engagement_rate: Mapped[float | None] = mapped_column(Float)
+    dimensions: Mapped[dict[str, object]] = mapped_column(JSON, nullable=False, default=dict)
+    source: Mapped[str] = mapped_column(String(64), nullable=False, default="provider")
+    collected_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=utcnow
+    )
+    provider_updated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class AnalyticsPlatformMetric(SocialBase):
+    __tablename__ = "analytics_platform_metrics"
+    __table_args__ = (
+        UniqueConstraint(
+            "workspace_id",
+            "provider",
+            "social_account_id",
+            "metric_date",
+            name="uq_analytics_platform_metric_bucket",
+        ),
+        Index("ix_analytics_platform_metrics_workspace_date", "workspace_id", "metric_date"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
+    workspace_id: Mapped[str] = mapped_column(String(120), nullable=False)
+    project_id: Mapped[str | None] = mapped_column(String(36))
+    social_account_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("social_accounts.id", ondelete="CASCADE"), nullable=False
+    )
+    provider: Mapped[str] = mapped_column(String(32), nullable=False)
+    metric_date: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    posts_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    views: Mapped[int | None] = mapped_column()
+    impressions: Mapped[int | None] = mapped_column()
+    likes: Mapped[int | None] = mapped_column()
+    comments: Mapped[int | None] = mapped_column()
+    shares: Mapped[int | None] = mapped_column()
+    engagement_rate: Mapped[float | None] = mapped_column(Float)
+    dimensions: Mapped[dict[str, object]] = mapped_column(JSON, nullable=False, default=dict)
+    source: Mapped[str] = mapped_column(String(64), nullable=False, default="provider")
+    collected_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=utcnow
+    )

app/analytics/repository.py

@@ -0,0 +1,385 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from sqlalchemy import or_, select
+from sqlalchemy.exc import IntegrityError
+
+from app.analytics.errors import (
+    AnalyticsIdempotencyConflictError,
+    AnalyticsNotFoundError,
+    AnalyticsValidationError,
+)
+from app.analytics.models import (
+    AnalyticsMetricSnapshot,
+    AnalyticsPlatformMetric,
+    AnalyticsPostMetric,
+    AnalyticsSyncRun,
+)
+from app.social.database import SocialDatabase
+from app.social.models import SocialPost, SocialPostTarget
+
+
+class AnalyticsRepository:
+    def __init__(self, database: SocialDatabase) -> None:
+        self.database = database
+
+    async def create_sync(self, run: AnalyticsSyncRun) -> AnalyticsSyncRun:
+        try:
+            async with self.database.session(run.workspace_id) as session:
+                session.add(run)
+                await session.commit()
+                await session.refresh(run)
+                return run
+        except IntegrityError as exc:
+            existing = await self.get_sync_by_idempotency(run.workspace_id, run.idempotency_key)
+            if existing is not None:
+                if (
+                    existing.date_from != run.date_from
+                    or existing.date_to != run.date_to
+                    or existing.provider != run.provider
+                    or existing.project_id != run.project_id
+                ):
+                    raise AnalyticsIdempotencyConflictError(
+                        "The analytics idempotency key was already used for a different request."
+                    ) from exc
+                return existing
+            raise
+
+    async def get_sync_by_idempotency(
+        self, workspace_id: str, idempotency_key: str
+    ) -> AnalyticsSyncRun | None:
+        async with self.database.session(workspace_id) as session:
+            return await session.scalar(
+                select(AnalyticsSyncRun).where(
+                    AnalyticsSyncRun.workspace_id == workspace_id,
+                    AnalyticsSyncRun.idempotency_key == idempotency_key,
+                )
+            )
+
+    async def get_sync(self, workspace_id: str, run_id: str) -> AnalyticsSyncRun:
+        async with self.database.session(workspace_id) as session:
+            run = await session.scalar(
+                select(AnalyticsSyncRun).where(
+                    AnalyticsSyncRun.id == run_id,
+                    AnalyticsSyncRun.workspace_id == workspace_id,
+                )
+            )
+            if run is None:
+                raise AnalyticsNotFoundError("Analytics sync run was not found.")
+            return run
+
+    async def list_syncs(
+        self, workspace_id: str, *, offset: int, limit: int
+    ) -> list[AnalyticsSyncRun]:
+        async with self.database.session(workspace_id) as session:
+            return list(
+                (
+                    await session.scalars(
+                        select(AnalyticsSyncRun)
+                        .where(AnalyticsSyncRun.workspace_id == workspace_id)
+                        .order_by(AnalyticsSyncRun.created_at.desc())
+                        .offset(offset)
+                        .limit(limit)
+                    )
+                ).all()
+            )
+
+    async def claim_due_syncs(self, *, limit: int = 4) -> list[AnalyticsSyncRun]:
+        async with self.database.worker_session() as session:
+            now = datetime.now(timezone.utc)
+            statement = (
+                select(AnalyticsSyncRun)
+                .where(
+                    AnalyticsSyncRun.status.in_(["queued", "retrying"]),
+                    (AnalyticsSyncRun.next_attempt_at.is_(None))
+                    | (AnalyticsSyncRun.next_attempt_at <= now),
+                )
+                .order_by(AnalyticsSyncRun.created_at)
+                .limit(limit)
+                .with_for_update(skip_locked=True)
+            )
+            runs = list((await session.scalars(statement)).all())
+            for run in runs:
+                run.status = "running"
+                run.started_at = now
+                run.attempt_count += 1
+                run.updated_at = now
+            await session.commit()
+            return runs
+
+    async def update_sync(
+        self,
+        run_id: str,
+        *,
+        status: str,
+        metrics_count: int | None = None,
+        error_code: str | None = None,
+        error_message: str | None = None,
+        next_attempt_at: datetime | None = None,
+    ) -> AnalyticsSyncRun:
+        async with self.database.worker_session() as session:
+            run = await session.get(AnalyticsSyncRun, run_id)
+            if run is None:
+                raise AnalyticsNotFoundError("Analytics sync run was not found.")
+            run.status = status
+            run.error_code = error_code
+            run.error_message = error_message
+            run.next_attempt_at = next_attempt_at
+            if metrics_count is not None:
+                run.metrics_count = metrics_count
+            if status in {"succeeded", "partial", "failed", "cancelled"}:
+                run.completed_at = datetime.now(timezone.utc)
+            run.updated_at = datetime.now(timezone.utc)
+            await session.commit()
+            await session.refresh(run)
+            return run
+
+    async def cancel_sync(self, workspace_id: str, run_id: str) -> AnalyticsSyncRun:
+        async with self.database.session(workspace_id) as session:
+            run = await session.scalar(
+                select(AnalyticsSyncRun).where(
+                    AnalyticsSyncRun.id == run_id,
+                    AnalyticsSyncRun.workspace_id == workspace_id,
+                )
+            )
+            if run is None:
+                raise AnalyticsNotFoundError("Analytics sync run was not found.")
+            if run.status not in {"queued", "running"}:
+                raise AnalyticsValidationError(
+                    "Only queued or running analytics synchronization can be cancelled."
+                )
+            run.status = "cancelled"
+            run.completed_at = datetime.now(timezone.utc)
+            run.updated_at = datetime.now(timezone.utc)
+            await session.commit()
+            await session.refresh(run)
+            return run
+
+    async def published_targets(
+        self,
+        workspace_id: str,
+        *,
+        project_id: str | None = None,
+        provider: str | None = None,
+        date_from: datetime | None = None,
+        date_to: datetime | None = None,
+    ) -> list[tuple[SocialPost, SocialPostTarget]]:
+        async with self.database.session(workspace_id) as session:
+            statement = (
+                select(SocialPost, SocialPostTarget)
+                .join(SocialPostTarget, SocialPostTarget.social_post_id == SocialPost.id)
+                .where(
+                    SocialPost.workspace_id == workspace_id,
+                    SocialPostTarget.external_post_id.is_not(None),
+                    SocialPostTarget.status == "published",
+                )
+            )
+            if project_id:
+                statement = statement.where(SocialPost.project_id == project_id)
+            if provider:
+                statement = statement.where(SocialPostTarget.provider == provider)
+            if date_from:
+                statement = statement.where(SocialPostTarget.published_at >= date_from)
+            if date_to:
+                statement = statement.where(SocialPostTarget.published_at <= date_to)
+            return list((await session.execute(statement)).all())
+
+    async def upsert_post_metric(
+        self,
+        *,
+        workspace_id: str,
+        post: SocialPost,
+        target: SocialPostTarget,
+        metric: dict[str, object],
+        collected_at: datetime,
+    ) -> AnalyticsPostMetric:
+        bucket = target.published_at or collected_at
+        async with self.database.session(workspace_id) as session:
+            existing = await session.scalar(
+                select(AnalyticsPostMetric).where(
+                    AnalyticsPostMetric.workspace_id == workspace_id,
+                    AnalyticsPostMetric.social_post_target_id == target.id,
+                    AnalyticsPostMetric.metric_date == bucket,
+                )
+            )
+            values = dict(
+                provider=target.provider,
+                views=metric.get("views"),
+                impressions=metric.get("impressions"),
+                likes=metric.get("likes"),
+                comments=metric.get("comments"),
+                shares=metric.get("shares"),
+                engagement_rate=metric.get("engagement_rate"),
+                dimensions=(
+                    metric.get("raw_metrics") if isinstance(metric.get("raw_metrics"), dict) else {}
+                ),
+                source="provider",
+                collected_at=collected_at,
+                external_post_id=target.external_post_id,
+            )
+            if existing is None:
+                existing = AnalyticsPostMetric(
+                    workspace_id=workspace_id,
+                    project_id=post.project_id,
+                    social_post_id=post.id,
+                    social_post_target_id=target.id,
+                    social_account_id=target.social_account_id,
+                    metric_date=bucket,
+                    **values,
+                )
+                session.add(existing)
+            else:
+                for key, value in values.items():
+                    setattr(existing, key, value)
+            if target.external_post_id:
+                for metric_name in (
+                    "views",
+                    "impressions",
+                    "likes",
+                    "comments",
+                    "shares",
+                    "engagement_rate",
+                ):
+                    metric_value = metric.get(metric_name)
+                    if not isinstance(metric_value, (int, float)) or isinstance(metric_value, bool):
+                        continue
+                    snapshot = await session.scalar(
+                        select(AnalyticsMetricSnapshot).where(
+                            AnalyticsMetricSnapshot.workspace_id == workspace_id,
+                            AnalyticsMetricSnapshot.provider == target.provider,
+                            AnalyticsMetricSnapshot.external_object_id == target.external_post_id,
+                            AnalyticsMetricSnapshot.metric_name == metric_name,
+                            AnalyticsMetricSnapshot.bucket_start == bucket,
+                        )
+                    )
+                    if snapshot is None:
+                        session.add(
+                            AnalyticsMetricSnapshot(
+                                workspace_id=workspace_id,
+                                project_id=post.project_id,
+                                social_post_id=post.id,
+                                social_account_id=target.social_account_id,
+                                provider=target.provider,
+                                external_object_id=target.external_post_id,
+                                metric_name=metric_name,
+                                metric_value=float(metric_value),
+                                bucket_start=bucket,
+                                dimensions={},
+                                source="provider",
+                                collected_at=collected_at,
+                            )
+                        )
+                    else:
+                        snapshot.metric_value = float(metric_value)
+                        snapshot.collected_at = collected_at
+            await session.flush()
+            day_start = bucket.astimezone(timezone.utc).replace(
+                hour=0, minute=0, second=0, microsecond=0
+            )
+            day_end = day_start.replace(hour=23, minute=59, second=59, microsecond=999999)
+            account_rows = list(
+                (
+                    await session.scalars(
+                        select(AnalyticsPostMetric).where(
+                            AnalyticsPostMetric.workspace_id == workspace_id,
+                            AnalyticsPostMetric.social_account_id == target.social_account_id,
+                            AnalyticsPostMetric.metric_date >= day_start,
+                            AnalyticsPostMetric.metric_date <= day_end,
+                        )
+                    )
+                ).all()
+            )
+            platform = await session.scalar(
+                select(AnalyticsPlatformMetric).where(
+                    AnalyticsPlatformMetric.workspace_id == workspace_id,
+                    AnalyticsPlatformMetric.provider == target.provider,
+                    AnalyticsPlatformMetric.social_account_id == target.social_account_id,
+                    AnalyticsPlatformMetric.metric_date == day_start,
+                )
+            )
+            aggregates: dict[str, int | float | None] = {}
+            for name in (
+                "views",
+                "impressions",
+                "likes",
+                "comments",
+                "shares",
+                "engagement_rate",
+            ):
+                metric_values = [
+                    getattr(item, name) for item in account_rows if getattr(item, name) is not None
+                ]
+                aggregates[name] = (
+                    (
+                        sum(metric_values) / len(metric_values)
+                        if name == "engagement_rate"
+                        else sum(metric_values)
+                    )
+                    if metric_values
+                    else None
+                )
+            if platform is None:
+                platform = AnalyticsPlatformMetric(
+                    workspace_id=workspace_id,
+                    project_id=post.project_id,
+                    social_account_id=target.social_account_id,
+                    provider=target.provider,
+                    metric_date=day_start,
+                )
+                session.add(platform)
+            platform.posts_count = len(account_rows)
+            platform.collected_at = collected_at
+            for name, value in aggregates.items():
+                setattr(platform, name, value)
+            await session.commit()
+            await session.refresh(existing)
+            return existing
+
+    async def metric_rows(
+        self,
+        workspace_id: str,
+        query: dict[str, object],
+    ) -> list[AnalyticsPostMetric]:
+        async with self.database.session(workspace_id) as session:
+            statement = select(AnalyticsPostMetric).where(
+                AnalyticsPostMetric.workspace_id == workspace_id,
+                AnalyticsPostMetric.metric_date >= query["date_from"],
+                AnalyticsPostMetric.metric_date <= query["date_to"],
+            )
+            for field, model_field in (
+                ("project_id", AnalyticsPostMetric.project_id),
+                ("provider", AnalyticsPostMetric.provider),
+                ("social_account_id", AnalyticsPostMetric.social_account_id),
+                ("post_id", AnalyticsPostMetric.social_post_id),
+            ):
+                value = query.get(field)
+                if value:
+                    statement = statement.where(model_field == value)
+            if query.get("search"):
+                pattern = f"%{str(query['search']).strip()}%"
+                statement = statement.join(
+                    SocialPost, SocialPost.id == AnalyticsPostMetric.social_post_id
+                ).where(
+                    or_(
+                        SocialPost.canonical_caption.ilike(pattern),
+                        SocialPost.id.ilike(pattern),
+                    )
+                )
+            return list((await session.scalars(statement)).all())
+
+    async def latest_sync(
+        self, workspace_id: str, *, provider: str | None = None, project_id: str | None = None
+    ) -> AnalyticsSyncRun | None:
+        async with self.database.session(workspace_id) as session:
+            statement = select(AnalyticsSyncRun).where(
+                AnalyticsSyncRun.workspace_id == workspace_id,
+                AnalyticsSyncRun.status.in_(["succeeded", "partial"]),
+            )
+            if provider:
+                statement = statement.where(AnalyticsSyncRun.provider == provider)
+            if project_id:
+                statement = statement.where(AnalyticsSyncRun.project_id == project_id)
+            return await session.scalar(
+                statement.order_by(AnalyticsSyncRun.completed_at.desc()).limit(1)
+            )

app/analytics/schemas.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+MetricName = Literal[
+    "views",
+    "impressions",
+    "likes",
+    "comments",
+    "shares",
+    "engagement_rate",
+    "reach",
+    "clicks",
+    "saves",
+    "watch_time",
+    "completion_rate",
+]
+Granularity = Literal["day", "week", "month"]
+
+
+class AnalyticsQuery(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    date_from: datetime | None = None
+    date_to: datetime | None = None
+    timezone: str = Field(default="UTC", min_length=1, max_length=100)
+    provider: str | None = Field(default=None, max_length=32)
+    project_id: str | None = Field(default=None, max_length=36)
+    social_account_id: str | None = Field(default=None, max_length=36)
+    post_id: str | None = Field(default=None, max_length=36)
+    metric: MetricName | None = None
+    granularity: Granularity = "day"
+    search: str | None = Field(default=None, max_length=200)
+    sort: Literal["date", "views", "engagement_rate", "likes", "comments", "shares"] = "date"
+    descending: bool = True
+    offset: int = Field(default=0, ge=0, le=100_000)
+    limit: int = Field(default=50, ge=1, le=500)
+
+
+class AnalyticsMetric(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    provider: str
+    post_id: str | None = None
+    project_id: str | None = None
+    metric_date: datetime
+    views: int | None = None
+    impressions: int | None = None
+    likes: int | None = None
+    comments: int | None = None
+    shares: int | None = None
+    engagement_rate: float | None = None
+    status: Literal["available", "unavailable", "unsupported", "not_synchronized"] = "available"
+    source: str = "provider"
+    collected_at: datetime | None = None
+
+
+class AnalyticsFreshness(BaseModel):
+    status: Literal["fresh", "stale", "not_synchronized", "partial", "failed"]
+    last_collected_at: datetime | None = None
+    last_sync_id: str | None = None
+    reason: str | None = None
+
+
+class AnalyticsOverview(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    date_from: datetime
+    date_to: datetime
+    timezone: str
+    timezone_source: Literal["requested", "utc_fallback"] = "requested"
+    totals: dict[str, int | float | None]
+    platforms: list[dict[str, Any]]
+    top_posts: list[AnalyticsMetric]
+    freshness: AnalyticsFreshness
+
+
+class AnalyticsTimeseries(BaseModel):
+    date_from: datetime
+    date_to: datetime
+    timezone: str
+    granularity: Granularity
+    metric: str
+    points: list[dict[str, Any]]
+    freshness: AnalyticsFreshness
+
+
+class AnalyticsSyncRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    date_from: datetime | None = None
+    date_to: datetime | None = None
+    timezone: str = Field(default="UTC", min_length=1, max_length=100)
+    provider: str | None = Field(default=None, max_length=32)
+    project_id: str | None = Field(default=None, max_length=36)
+    idempotency_key: str | None = Field(default=None, min_length=8, max_length=255)
+
+
+class AnalyticsSyncRunView(BaseModel):
+    model_config = ConfigDict(from_attributes=True, extra="forbid")
+
+    id: str
+    status: Literal["queued", "running", "succeeded", "partial", "failed", "cancelled"]
+    provider: str | None = None
+    project_id: str | None = None
+    date_from: datetime
+    date_to: datetime
+    timezone: str
+    attempt_count: int
+    metrics_count: int
+    error_code: str | None = None
+    error_message: str | None = None
+    created_at: datetime
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+    updated_at: datetime
+
+
+class AnalyticsCapabilities(BaseModel):
+    provider: str
+    implementation_status: str
+    status: Literal["available", "unsupported", "unavailable"]
+    metrics: list[str]
+    required_scopes: list[str] = Field(default_factory=list)
+
+
+class AnalyticsSyncList(BaseModel):
+    items: list[AnalyticsSyncRunView]
+    offset: int
+    limit: int
+
+
+class AnalyticsPostList(BaseModel):
+    items: list[AnalyticsMetric]
+    offset: int
+    limit: int
+    freshness: AnalyticsFreshness

app/analytics/service.py

@@ -0,0 +1,379 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import datetime, timedelta, timezone
+from typing import Any
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from app.analytics.errors import AnalyticsValidationError
+from app.analytics.models import AnalyticsSyncRun
+from app.analytics.repository import AnalyticsRepository
+from app.analytics.schemas import (
+    AnalyticsCapabilities,
+    AnalyticsFreshness,
+    AnalyticsMetric,
+    AnalyticsOverview,
+    AnalyticsPostList,
+    AnalyticsQuery,
+    AnalyticsSyncRequest,
+    AnalyticsSyncRunView,
+    AnalyticsTimeseries,
+)
+from app.core.logger import get_logger
+from app.social.providers.registry import ProviderRegistry
+from app.social.services.analytics_service import AnalyticsService as SocialAnalyticsService
+from app.social.services.audit_service import SocialAuditService
+
+logger = get_logger(__name__)
+COMMON_METRICS = ("views", "impressions", "likes", "comments", "shares", "engagement_rate")
+PROVIDER_METRICS: dict[str, tuple[str, ...]] = {
+    "facebook": ("views", "impressions", "likes", "comments", "shares"),
+    "instagram": ("views", "likes", "comments", "shares"),
+    "tiktok": ("views", "likes", "comments", "shares"),
+    "x": ("impressions", "likes", "comments", "shares"),
+    "youtube": ("views", "likes", "comments"),
+    "linkedin": ("impressions", "likes", "comments", "shares", "engagement_rate"),
+}
+
+
+class AnalyticsDomainService:
+    """Tenant-scoped analytics aggregation over provider-reported snapshots."""
+
+    def __init__(
+        self,
+        repository: AnalyticsRepository,
+        providers: ProviderRegistry,
+        social_analytics: SocialAnalyticsService,
+        accounts: object,
+        audit: SocialAuditService,
+        projects: object | None = None,
+    ) -> None:
+        self.repository = repository
+        self.providers = providers
+        self.social_analytics = social_analytics
+        self.accounts = accounts
+        self.audit = audit
+        self.projects = projects
+        self.ready = False
+
+    async def initialize(self, social_ready: bool) -> None:
+        self.ready = social_ready
+
+    def ensure_ready(self) -> None:
+        if not self.ready:
+            from app.social.domain.errors import SocialProviderUnavailableError
+
+            raise SocialProviderUnavailableError(
+                "Analytics database schema is unavailable. Apply the analytics migration."
+            )
+
+    @staticmethod
+    def _range(query: AnalyticsQuery) -> tuple[datetime, datetime, str]:
+        end = query.date_to or datetime.now(timezone.utc)
+        start = query.date_from or end - timedelta(days=30)
+        if start.tzinfo is None or end.tzinfo is None:
+            raise AnalyticsValidationError("Analytics dates must include a UTC offset.")
+        if end <= start:
+            raise AnalyticsValidationError("date_to must be after date_from.")
+        if end - start > timedelta(days=366):
+            raise AnalyticsValidationError("Analytics date ranges are limited to 366 days.")
+        try:
+            ZoneInfo(query.timezone)
+        except ZoneInfoNotFoundError as exc:
+            raise AnalyticsValidationError("timezone must be a valid IANA timezone.") from exc
+        return start.astimezone(timezone.utc), end.astimezone(timezone.utc), query.timezone
+
+    @staticmethod
+    def _metric_view(row: Any) -> AnalyticsMetric:
+        return AnalyticsMetric(
+            provider=row.provider,
+            post_id=row.social_post_id,
+            project_id=row.project_id,
+            metric_date=row.metric_date,
+            views=row.views,
+            impressions=row.impressions,
+            likes=row.likes,
+            comments=row.comments,
+            shares=row.shares,
+            engagement_rate=row.engagement_rate,
+            collected_at=row.collected_at,
+            source=row.source,
+        )
+
+    async def capabilities(self) -> list[AnalyticsCapabilities]:
+        result: list[AnalyticsCapabilities] = []
+        for adapter in self.providers.list():
+            capabilities = adapter.capabilities
+            available = bool(capabilities.analytics)
+            result.append(
+                AnalyticsCapabilities(
+                    provider=capabilities.provider.value,
+                    implementation_status=capabilities.implementation_status,
+                    status="available" if available else "unsupported",
+                    metrics=(
+                        list(PROVIDER_METRICS.get(capabilities.provider.value, ()))
+                        if available
+                        else []
+                    ),
+                    required_scopes=list(capabilities.analytics_required_scopes),
+                )
+            )
+        return result
+
+    async def create_sync(
+        self, workspace_id: str, user_id: str, payload: AnalyticsSyncRequest
+    ) -> AnalyticsSyncRunView:
+        query = AnalyticsQuery(
+            date_from=payload.date_from,
+            date_to=payload.date_to,
+            timezone=payload.timezone,
+            provider=payload.provider,
+            project_id=payload.project_id,
+        )
+        start, end, tz = self._range(query)
+        if not payload.idempotency_key:
+            raise AnalyticsValidationError(
+                "Idempotency-Key is required for analytics synchronization."
+            )
+        if payload.provider:
+            self.providers.get(payload.provider)
+        if payload.project_id and self.projects is not None:
+            await self.projects.get(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                project_id=payload.project_id,
+            )
+        run = await self.repository.create_sync(
+            AnalyticsSyncRun(
+                workspace_id=workspace_id,
+                project_id=payload.project_id,
+                provider=payload.provider,
+                date_from=start,
+                date_to=end,
+                timezone=tz,
+                idempotency_key=payload.idempotency_key,
+                requested_by=user_id,
+            )
+        )
+        await self.audit.record(
+            workspace_id=workspace_id,
+            event_type="analytics.sync_requested",
+            metadata={"sync_run_id": run.id, "provider": payload.provider},
+        )
+        return self._sync_view(run)
+
+    async def sync_once(self, run: AnalyticsSyncRun) -> AnalyticsSyncRunView:
+        targets = await self.repository.published_targets(
+            run.workspace_id,
+            project_id=run.project_id,
+            provider=run.provider,
+            date_from=run.date_from,
+            date_to=run.date_to,
+        )
+        await self.audit.record(
+            workspace_id=run.workspace_id,
+            event_type="analytics.sync_started",
+            metadata={"sync_run_id": run.id},
+        )
+        errors = 0
+        count = 0
+        by_post: dict[str, tuple[Any, list[Any]]] = {}
+        for post, target in targets:
+            by_post.setdefault(post.id, (post, []))[1].append(target)
+        for post, post_targets in by_post.values():
+            try:
+                latest = await self.repository.get_sync(run.workspace_id, run.id)
+                if latest.status == "cancelled":
+                    return self._sync_view(latest)
+                result = await self.social_analytics.post(run.workspace_id, post.id)
+                for target in post_targets:
+                    matches = [
+                        item
+                        for item in result.get("metrics", [])
+                        if isinstance(item, dict) and item.get("provider") == target.provider
+                    ]
+                    if not matches:
+                        errors += 1
+                        continue
+                    metric = matches[-1]
+                    await self.repository.upsert_post_metric(
+                        workspace_id=run.workspace_id,
+                        post=post,
+                        target=target,
+                        metric=metric,
+                        collected_at=datetime.now(timezone.utc),
+                    )
+                    count += 1
+                if result.get("unavailable"):
+                    errors += 1
+            except Exception as exc:
+                errors += 1
+                logger.warning(
+                    "analytics target synchronization failed",
+                    extra={"sync_run_id": run.id, "post_id": post.id},
+                )
+                if not getattr(exc, "code", None):
+                    logger.debug("analytics sync exception", exc_info=True)
+        status = (
+            "failed" if targets and count == 0 and errors else "partial" if errors else "succeeded"
+        )
+        if not targets:
+            status = "succeeded"
+        updated = await self.repository.update_sync(run.id, status=status, metrics_count=count)
+        await self.audit.record(
+            workspace_id=run.workspace_id,
+            event_type=(
+                "analytics.sync_completed" if status != "failed" else "analytics.sync_failed"
+            ),
+            metadata={"sync_run_id": run.id, "status": status, "metrics_count": count},
+        )
+        return self._sync_view(updated)
+
+    async def overview(self, workspace_id: str, query: AnalyticsQuery) -> AnalyticsOverview:
+        start, end, tz = self._range(query)
+        rows = await self.repository.metric_rows(
+            workspace_id,
+            {
+                "date_from": start,
+                "date_to": end,
+                "provider": query.provider,
+                "project_id": query.project_id,
+                "social_account_id": query.social_account_id,
+                "post_id": query.post_id,
+                "search": query.search,
+            },
+        )
+        totals = self._totals(rows)
+        grouped: dict[str, list[Any]] = defaultdict(list)
+        for row in rows:
+            grouped[row.provider].append(row)
+        platforms = [
+            {"provider": provider, "posts": len(items), **self._totals(items)}
+            for provider, items in sorted(grouped.items())
+        ]
+        top = sorted(
+            rows, key=lambda row: self._sort_value(row, query.sort), reverse=query.descending
+        )[:10]
+        return AnalyticsOverview(
+            date_from=start,
+            date_to=end,
+            timezone=tz,
+            timezone_source="requested" if query.timezone != "UTC" else "utc_fallback",
+            totals=totals,
+            platforms=platforms,
+            top_posts=[self._metric_view(row) for row in top],
+            freshness=await self._freshness(workspace_id, query),
+        )
+
+    async def timeseries(self, workspace_id: str, query: AnalyticsQuery) -> AnalyticsTimeseries:
+        start, end, tz_name = self._range(query)
+        rows = await self.repository.metric_rows(
+            workspace_id,
+            {
+                "date_from": start,
+                "date_to": end,
+                "provider": query.provider,
+                "project_id": query.project_id,
+                "social_account_id": query.social_account_id,
+                "post_id": query.post_id,
+                "search": query.search,
+            },
+        )
+        zone = ZoneInfo(tz_name)
+        points: dict[str, dict[str, Any]] = {}
+        for row in rows:
+            local = row.metric_date.astimezone(zone)
+            if query.granularity == "month":
+                key = local.strftime("%Y-%m-01")
+            elif query.granularity == "week":
+                monday = local.date() - timedelta(days=local.weekday())
+                key = monday.isoformat()
+            else:
+                key = local.date().isoformat()
+            item = points.setdefault(key, {"bucket": key, "value": 0, "posts": 0})
+            value = getattr(row, query.metric or "views")
+            if value is not None:
+                item["value"] += value
+            item["posts"] += 1
+        return AnalyticsTimeseries(
+            date_from=start,
+            date_to=end,
+            timezone=tz_name,
+            granularity=query.granularity,
+            metric=query.metric or "views",
+            points=[points[key] for key in sorted(points)],
+            freshness=await self._freshness(workspace_id, query),
+        )
+
+    async def posts(self, workspace_id: str, query: AnalyticsQuery) -> AnalyticsPostList:
+        start, end, _ = self._range(query)
+        rows = await self.repository.metric_rows(
+            workspace_id,
+            {
+                "date_from": start,
+                "date_to": end,
+                "provider": query.provider,
+                "project_id": query.project_id,
+                "social_account_id": query.social_account_id,
+                "post_id": query.post_id,
+                "search": query.search,
+            },
+        )
+        rows.sort(key=lambda row: self._sort_value(row, query.sort), reverse=query.descending)
+        return AnalyticsPostList(
+            items=[
+                self._metric_view(row) for row in rows[query.offset : query.offset + query.limit]
+            ],
+            offset=query.offset,
+            limit=query.limit,
+            freshness=await self._freshness(workspace_id, query),
+        )
+
+    async def post(
+        self, workspace_id: str, post_id: str, query: AnalyticsQuery
+    ) -> AnalyticsPostList:
+        query.post_id = post_id
+        return await self.posts(workspace_id, query)
+
+    async def _freshness(self, workspace_id: str, query: AnalyticsQuery) -> AnalyticsFreshness:
+        run = await self.repository.latest_sync(
+            workspace_id, provider=query.provider, project_id=query.project_id
+        )
+        if run is None:
+            return AnalyticsFreshness(
+                status="not_synchronized", reason="No analytics sync has completed."
+            )
+        status = (
+            "fresh"
+            if run.completed_at
+            and run.completed_at >= datetime.now(timezone.utc) - timedelta(hours=24)
+            else "stale"
+        )
+        if run.status == "partial":
+            status = "partial"
+        return AnalyticsFreshness(
+            status=status, last_collected_at=run.completed_at, last_sync_id=run.id
+        )
+
+    @staticmethod
+    def _totals(rows: list[Any]) -> dict[str, int | float | None]:
+        result: dict[str, int | float | None] = {}
+        for name in COMMON_METRICS:
+            values = [getattr(row, name) for row in rows if getattr(row, name) is not None]
+            result[name] = (
+                (sum(values) / len(values) if name == "engagement_rate" else sum(values))
+                if values
+                else None
+            )
+        return result
+
+    @staticmethod
+    def _sort_value(row: Any, field: str) -> float:
+        if field == "date":
+            return row.metric_date.timestamp()
+        value = getattr(row, field, None)
+        return float(value) if isinstance(value, (int, float)) else 0.0
+
+    @staticmethod
+    def _sync_view(run: AnalyticsSyncRun) -> AnalyticsSyncRunView:
+        return AnalyticsSyncRunView.model_validate(run, from_attributes=True)

app/analytics/workers/__init__.py

@@ -0,0 +1 @@
+"""Durable analytics synchronization workers."""

app/analytics/workers/sync.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import asyncio
+import random
+from datetime import datetime, timedelta, timezone
+
+from app.analytics.service import AnalyticsDomainService
+from app.core.logger import get_logger
+from app.social.database import SocialDatabase
+
+logger = get_logger(__name__)
+
+
+class AnalyticsSyncWorker:
+    """Claims durable sync runs and executes bounded provider synchronization."""
+
+    def __init__(
+        self,
+        analytics: AnalyticsDomainService,
+        database: SocialDatabase,
+        *,
+        interval_seconds: int,
+        concurrency: int = 2,
+    ) -> None:
+        self.analytics = analytics
+        self.database = database
+        self.interval_seconds = max(1, interval_seconds)
+        self.concurrency = max(1, min(concurrency, 8))
+        self._task: asyncio.Task[None] | None = None
+        self._stop = asyncio.Event()
+
+    async def start(self) -> None:
+        if self._task is not None or not self.analytics.ready:
+            return
+        self._stop.clear()
+        self._task = asyncio.create_task(self._run(), name="analytics-sync-worker")
+
+    async def stop(self) -> None:
+        self._stop.set()
+        if self._task is not None:
+            self._task.cancel()
+            await asyncio.gather(self._task, return_exceptions=True)
+            self._task = None
+
+    async def run_once(self) -> None:
+        if not self.analytics.ready:
+            return
+        async with self.database.worker_boundary():
+            runs = await self.analytics.repository.claim_due_syncs(limit=self.concurrency)
+            await asyncio.gather(*(self._execute(run) for run in runs))
+
+    async def _execute(self, run) -> None:
+        try:
+            latest = await self.analytics.repository.get_sync(run.workspace_id, run.id)
+            if latest.status == "cancelled":
+                return
+            await self.analytics.sync_once(run)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            retryable = run.attempt_count < 3
+            if retryable:
+                delay = min(900, 30 * (2 ** max(0, run.attempt_count - 1))) + random.randint(0, 10)
+                await self.analytics.repository.update_sync(
+                    run.id,
+                    status="queued",
+                    error_code=getattr(exc, "code", "ANALYTICS_SYNC_RETRY"),
+                    error_message="Analytics synchronization will be retried.",
+                    next_attempt_at=datetime.now(timezone.utc) + timedelta(seconds=delay),
+                )
+            else:
+                await self.analytics.repository.update_sync(
+                    run.id,
+                    status="failed",
+                    error_code=getattr(exc, "code", "ANALYTICS_SYNC_FAILED"),
+                    error_message="Analytics synchronization failed.",
+                )
+                await self.analytics.audit.record(
+                    workspace_id=run.workspace_id,
+                    event_type="analytics.sync_failed",
+                    metadata={"sync_run_id": run.id, "error_code": getattr(exc, "code", None)},
+                )
+            logger.warning(
+                "analytics sync execution failed",
+                extra={"sync_run_id": run.id, "attempt": run.attempt_count},
+            )
+
+    async def _run(self) -> None:
+        while not self._stop.is_set():
+            try:
+                await self.run_once()
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                logger.exception("analytics sync worker iteration failed")
+            try:
+                await asyncio.wait_for(self._stop.wait(), timeout=self.interval_seconds)
+            except TimeoutError:
+                pass

app/api/api_keys.py

@@ -38,6 +38,9 @@ async def current_auth_context(request: Request) -> AuthContextView:
         role=context.role,
         scopes=sorted(context.scopes),
         expires_at=context.expires_at,
+        workspace_id=context.workspace_id,
+        user_id=context.user_id,
+        membership_role=context.membership_role,
     )
 
 
@@ -80,7 +83,10 @@ async def create_api_key(request: Request, payload: APIKeyCreate) -> APIKeyCreat
     context = request.state.auth
     try:
         record, secret = await request.app.state.container.api_keys.create(
-            payload, created_by=context.api_key_id
+            payload,
+            created_by=context.api_key_id,
+            workspace_id=context.workspace_id,
+            user_id=context.user_id,
         )
     except APIKeyConflictError as exc:
         raise HTTPException(status_code=409, detail=str(exc)) from exc

app/api/generation.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Header, HTTPException, Query, Request, status
+
+from app.generation.schemas.requests import (
+    GenerationJobView,
+    GenerationProviderView,
+    GenerationRequestCreate,
+    GenerationRequestView,
+)
+from app.generation.model_registry import GenerationModelView
+
+router = APIRouter(prefix="/v1/generation", tags=["generation"])
+
+
+def _generation(request: Request):
+    service = request.app.state.container.generation
+    service.ensure_ready()
+    return service
+
+
+def _identity(request: Request) -> tuple[str, str]:
+    context = request.state.auth
+    if not context.workspace_id or not context.user_id:
+        # The credential itself is never a workspace.  API-key middleware
+        # resolves the authoritative membership before this route runs.
+        raise HTTPException(status_code=403, detail="No active workspace membership.")
+    return context.workspace_id, context.user_id
+
+
+@router.get("/providers", response_model=list[GenerationProviderView])
+async def list_providers(request: Request) -> list[GenerationProviderView]:
+    return _generation(request).list_providers()
+
+
+@router.get(
+    "/providers/{provider}", response_model=GenerationProviderView
+)
+async def get_provider(request: Request, provider: str) -> GenerationProviderView:
+    return _generation(request).get_provider(provider)
+
+
+@router.get("/models", response_model=list[GenerationModelView])
+async def list_models(
+    request: Request,
+    provider: str | None = Query(default=None, min_length=1, max_length=64),
+) -> list[GenerationModelView]:
+    return _generation(request).list_models(provider=provider)
+
+
+@router.get("/providers/{provider}/models/{model_id}", response_model=GenerationModelView)
+async def get_model(
+    request: Request, provider: str, model_id: str
+) -> GenerationModelView:
+    return _generation(request).get_model(provider, model_id)
+
+
+@router.post(
+    "/requests",
+    response_model=GenerationRequestView,
+    status_code=status.HTTP_202_ACCEPTED,
+)
+async def create_request(
+    request: Request,
+    payload: GenerationRequestCreate,
+    idempotency_key: Annotated[
+        str, Header(alias="Idempotency-Key", min_length=8, max_length=255)
+    ],
+) -> GenerationRequestView:
+    workspace_id, user_id = _identity(request)
+    return await _generation(request).create(
+        workspace_id=workspace_id,
+        user_id=user_id,
+        payload=payload,
+        idempotency_key=idempotency_key,
+    )
+
+
+@router.get("/requests", response_model=list[GenerationRequestView])
+async def list_requests(
+    request: Request,
+    offset: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=500),
+) -> list[GenerationRequestView]:
+    workspace_id, user_id = _identity(request)
+    return await _generation(request).list_requests(
+        workspace_id, user_id, offset=offset, limit=limit
+    )
+
+
+@router.get("/requests/{generation_request_id}", response_model=GenerationRequestView)
+async def get_request(
+    request: Request, generation_request_id: str
+) -> GenerationRequestView:
+    workspace_id, user_id = _identity(request)
+    return await _generation(request).get_request(
+        workspace_id, user_id, generation_request_id
+    )
+
+
+@router.get("/jobs/{generation_job_id}", response_model=GenerationJobView)
+async def get_job(request: Request, generation_job_id: str) -> GenerationJobView:
+    workspace_id, user_id = _identity(request)
+    return await _generation(request).get_job(
+        workspace_id, user_id, generation_job_id
+    )
+
+
+@router.post(
+    "/jobs/{generation_job_id}/cancel", response_model=GenerationJobView
+)
+async def cancel_job(request: Request, generation_job_id: str) -> GenerationJobView:
+    workspace_id, user_id = _identity(request)
+    return await _generation(request).cancel(
+        workspace_id, user_id, generation_job_id
+    )

app/api/media.py

@@ -7,7 +7,9 @@ import aiofiles
 from fastapi import APIRouter, Request
 from fastapi.responses import StreamingResponse
 
+from app.core.exceptions import NotFoundError
 from app.core.response import SuccessResponse
+from app.security.assets import CanonicalAssetNotFoundError
 from app.services.media_service import MediaProcessor, Operation
 
 router = APIRouter(tags=["media"])
@@ -34,7 +36,25 @@ async def stream_file(path: Path) -> AsyncIterator[bytes]:
 async def download_media(request: Request, request_id: str, filename: str) -> StreamingResponse:
     request.state.operation = "media.download"
     container = request.app.state.container
-    path = container.cleanup.resolve_download(request_id, filename)
+    # The filesystem locator is not an authorization token. In authenticated
+    # deployments an output must have been issued by the pipeline to the
+    # caller's authoritative workspace before it can be downloaded.
+    if container.settings.auth_enabled:
+        context = getattr(request.state, "auth", None)
+        if context is None or not context.workspace_id:
+            raise NotFoundError("Output file not found")
+        try:
+            asset = await container.assets.get_owned(
+                workspace_id=context.workspace_id,
+                request_id=request_id,
+                filename=filename,
+            )
+            path = container.cleanup.resolve_download(request_id, asset.filename)
+            await container.assets.verify_file(asset, path)
+        except CanonicalAssetNotFoundError as exc:
+            raise NotFoundError("Output file not found") from exc
+    else:
+        path = container.cleanup.resolve_download(request_id, filename)
     media_type = container.validator.infer_mime(path)
     headers = {
         "Content-Disposition": f'attachment; filename="{path.name}"',

app/api/social.py

@@ -1,24 +1,42 @@
 from __future__ import annotations
 
+from datetime import datetime
 from typing import Annotated
 
-from fastapi import APIRouter, Header, Query, Request, Response, status
+from fastapi import APIRouter, Header, HTTPException, Query, Request, Response, status
 
 from app.social.schemas.accounts import (
     SocialAccountConnectRequest,
     SocialAccountSelectionRequest,
     SocialAccountView,
     SocialConnectResponse,
-    SocialPublishOptionsView,
     SocialProviderView,
+    SocialPublishOptionsView,
 )
 from app.social.schemas.assets import (
     SocialMediaAssetRegister,
     SocialMediaAssetView,
 )
 from app.social.schemas.jobs import SocialJobView
-from app.social.schemas.posts import SocialPostCreate, SocialPostView
-from app.social.schemas.scheduling import SocialScheduleCreate, SocialScheduleView
+from app.social.schemas.operations import (
+    PublishingBatchView,
+    PublishingBulkRequest,
+    PublishingCalendarView,
+    PublishingContextView,
+    PublishingQueueView,
+)
+from app.social.schemas.posts import (
+    SocialPostCreate,
+    SocialPostDuplicateRequest,
+    SocialPostPatch,
+    SocialPostValidation,
+    SocialPostView,
+)
+from app.social.schemas.scheduling import (
+    SocialRescheduleRequest,
+    SocialScheduleCreate,
+    SocialScheduleView,
+)
 
 router = APIRouter(prefix="/v1/social", tags=["social automation"])
 
@@ -31,9 +49,11 @@ def _social(request: Request):
 
 def _identity(request: Request) -> tuple[str, str]:
     context = request.state.auth
-    # Phase 1 isolation: the authenticated API-key identity is the tenant
-    # boundary until the backend gains a native workspace membership model.
-    return context.api_key_id, context.api_key_id
+    if not context.workspace_id or not context.user_id:
+        # Tenant resolution is performed by APIKeyService after credential
+        # verification. Never fall back to treating an API-key ID as a tenant.
+        raise HTTPException(status_code=403, detail="No active workspace membership.")
+    return context.workspace_id, context.user_id
 
 
 async def _audit(
@@ -45,11 +65,11 @@ async def _audit(
     post_id: str | None = None,
     job_id: str | None = None,
 ) -> None:
-    workspace_id, user_id = _identity(request)
+    workspace_id, _ = _identity(request)
     await request.app.state.container.social.audit.record(
         workspace_id=workspace_id,
         event_type=event_type,
-        api_key_id=user_id,
+        api_key_id=request.state.auth.api_key_id,
         request_id=request.state.request_id,
         provider=provider,
         social_account_id=account_id,
@@ -63,9 +83,7 @@ async def list_providers(request: Request) -> list[SocialProviderView]:
     return request.app.state.container.social.accounts.list_providers()
 
 
-@router.get(
-    "/providers/{provider}/capabilities", response_model=SocialProviderView
-)
+@router.get("/providers/{provider}/capabilities", response_model=SocialProviderView)
 async def provider_capabilities(request: Request, provider: str) -> SocialProviderView:
     return request.app.state.container.social.accounts.get_provider(provider)
 
@@ -95,9 +113,7 @@ async def list_accounts(
     limit: int = Query(default=100, ge=1, le=500),
 ) -> list[SocialAccountView]:
     workspace_id, _ = _identity(request)
-    return await _social(request).accounts.list(
-        workspace_id, offset=offset, limit=limit
-    )
+    return await _social(request).accounts.list(workspace_id, offset=offset, limit=limit)
 
 
 @router.post("/accounts/select", response_model=list[SocialAccountView])
@@ -105,9 +121,7 @@ async def select_discovered_accounts(
     request: Request, payload: SocialAccountSelectionRequest
 ) -> list[SocialAccountView]:
     workspace_id, _ = _identity(request)
-    selected = await _social(request).accounts.select_discovered(
-        workspace_id, payload.account_ids
-    )
+    selected = await _social(request).accounts.select_discovered(workspace_id, payload.account_ids)
     for account in selected:
         await _audit(
             request,
@@ -132,14 +146,10 @@ async def get_account_publish_options(
     request: Request, account_id: str
 ) -> SocialPublishOptionsView:
     workspace_id, _ = _identity(request)
-    return await _social(request).publishing.publish_options(
-        workspace_id, account_id
-    )
+    return await _social(request).publishing.publish_options(workspace_id, account_id)
 
 
-@router.post(
-    "/accounts/{provider}/connect", response_model=SocialConnectResponse
-)
+@router.post("/accounts/{provider}/connect", response_model=SocialConnectResponse)
 async def connect_account(
     request: Request, provider: str, payload: SocialAccountConnectRequest
 ) -> SocialConnectResponse:
@@ -162,9 +172,7 @@ async def connect_account(
 async def oauth_callback(
     request: Request,
     provider: str,
-    state: Annotated[
-        str, Query(min_length=32, max_length=255, pattern=r"^[A-Za-z0-9_-]+$")
-    ],
+    state: Annotated[str, Query(min_length=32, max_length=255, pattern=r"^[A-Za-z0-9_-]+$")],
     code: Annotated[str | None, Query(min_length=1, max_length=4096)] = None,
     error: Annotated[str | None, Query(max_length=128)] = None,
 ) -> SocialAccountView:
@@ -181,9 +189,7 @@ async def oauth_callback(
 @router.post("/accounts/{account_id}/refresh", response_model=SocialAccountView)
 async def refresh_account(request: Request, account_id: str) -> SocialAccountView:
     workspace_id, _ = _identity(request)
-    result = await _social(request).oauth.refresh(
-        workspace_id=workspace_id, account_id=account_id
-    )
+    result = await _social(request).oauth.refresh(workspace_id=workspace_id, account_id=account_id)
     await _audit(request, "SOCIAL_ACCOUNT_REAUTHORIZED", account_id=account_id)
     return result
 
@@ -202,9 +208,7 @@ async def disconnect_account(request: Request, account_id: str) -> Response:
     return Response(status_code=status.HTTP_204_NO_CONTENT)
 
 
-@router.post(
-    "/posts", response_model=SocialPostView, status_code=status.HTTP_201_CREATED
-)
+@router.post("/posts", response_model=SocialPostView, status_code=status.HTTP_201_CREATED)
 async def create_post(
     request: Request,
     payload: SocialPostCreate,
@@ -220,6 +224,8 @@ async def create_post(
         idempotency_key=idempotency_key,
     )
     await _audit(request, "SOCIAL_POST_CREATED", post_id=result.id)
+    if result.publish_mode.value == "draft":
+        await _audit(request, "publishing.draft_created", post_id=result.id)
     return result
 
 
@@ -228,10 +234,18 @@ async def list_posts(
     request: Request,
     offset: int = Query(default=0, ge=0),
     limit: int = Query(default=100, ge=1, le=500),
+    post_status: str | None = Query(default=None, alias="status", max_length=32),
+    project_id: str | None = Query(default=None, max_length=36),
+    search: str | None = Query(default=None, max_length=200),
 ) -> list[SocialPostView]:
     workspace_id, _ = _identity(request)
     return await _social(request).publishing.list(
-        workspace_id, offset=offset, limit=limit
+        workspace_id,
+        offset=offset,
+        limit=limit,
+        status=post_status,
+        project_id=project_id,
+        search=search,
     )
 
 
@@ -241,6 +255,76 @@ async def get_post(request: Request, post_id: str) -> SocialPostView:
     return await _social(request).publishing.get(workspace_id, post_id)
 
 
+@router.patch("/posts/{post_id}", response_model=SocialPostView)
+async def update_post(request: Request, post_id: str, payload: SocialPostPatch) -> SocialPostView:
+    workspace_id, _ = _identity(request)
+    result = await _social(request).operations.update_draft(workspace_id, post_id, payload)
+    await _audit(request, "publishing.draft_updated", post_id=post_id)
+    return result
+
+
+@router.get("/drafts", response_model=list[SocialPostView])
+async def list_drafts(
+    request: Request,
+    offset: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=500),
+    search: str | None = Query(default=None, max_length=200),
+) -> list[SocialPostView]:
+    workspace_id, _ = _identity(request)
+    posts = await _social(request).publishing.list(
+        workspace_id,
+        offset=offset,
+        limit=limit,
+        search=search,
+    )
+    return [
+        post
+        for post in posts
+        if post.status.value in {"draft", "ready", "failed"} and post.publish_mode.value == "draft"
+    ]
+
+
+@router.patch("/drafts/{post_id}", response_model=SocialPostView)
+async def update_draft(request: Request, post_id: str, payload: SocialPostPatch) -> SocialPostView:
+    return await update_post(request, post_id, payload)
+
+
+@router.delete("/drafts/{post_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_draft(request: Request, post_id: str) -> Response:
+    workspace_id, _ = _identity(request)
+    await _social(request).operations.delete_draft(workspace_id, post_id)
+    await _audit(request, "publishing.draft_deleted", post_id=post_id)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@router.post("/posts/{post_id}/duplicate", response_model=SocialPostView)
+async def duplicate_post(
+    request: Request,
+    post_id: str,
+    payload: SocialPostDuplicateRequest,
+    idempotency_key: str = Header(alias="Idempotency-Key", min_length=8, max_length=255),
+) -> SocialPostView:
+    workspace_id, user_id = _identity(request)
+    result = await _social(request).operations.duplicate(
+        workspace_id,
+        user_id,
+        post_id,
+        payload,
+        idempotency_key=idempotency_key,
+    )
+    await _audit(request, "publishing.duplicated", post_id=result.id)
+    return result
+
+
+@router.post("/posts/{post_id}/validate", response_model=SocialPostValidation)
+async def validate_post(request: Request, post_id: str) -> SocialPostValidation:
+    workspace_id, _ = _identity(request)
+    result = await _social(request).publishing.validate_post_targets(workspace_id, post_id)
+    await _audit(request, "SOCIAL_POST_VALIDATED", post_id=post_id)
+    await _audit(request, "publishing.validated", post_id=post_id)
+    return result
+
+
 @router.delete("/posts/{post_id}", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_post(request: Request, post_id: str) -> Response:
     workspace_id, _ = _identity(request)
@@ -263,6 +347,7 @@ async def publish_post(
     jobs = await _social(request).publishing.queue(
         workspace_id, post_id, idempotency_key=idempotency_key
     )
+    await _audit(request, "SOCIAL_POST_PUBLISH_STARTED", post_id=post_id)
     return jobs
 
 
@@ -271,19 +356,134 @@ async def schedule_post(
     request: Request, post_id: str, payload: SocialScheduleCreate
 ) -> SocialScheduleView:
     workspace_id, _ = _identity(request)
-    await _social(request).publishing.validate_post_targets(workspace_id, post_id)
-    schedule = await _social(request).scheduling.schedule(
-        workspace_id, post_id, payload
-    )
+    validation = await _social(request).publishing.validate_post_targets(workspace_id, post_id)
+    if not validation.valid:
+        raise HTTPException(
+            status_code=422,
+            detail=validation.model_dump(mode="json"),
+        )
+    schedule = await _social(request).scheduling.schedule(workspace_id, post_id, payload)
     await _audit(request, "SOCIAL_SCHEDULE_CREATED", post_id=post_id)
+    await _audit(request, "SOCIAL_POST_SCHEDULED", post_id=post_id)
+    await _audit(request, "publishing.scheduled", post_id=post_id)
     return schedule
 
 
+@router.post("/posts/{post_id}/reschedule", response_model=SocialScheduleView)
+async def reschedule_post(
+    request: Request, post_id: str, payload: SocialRescheduleRequest
+) -> SocialScheduleView:
+    workspace_id, _ = _identity(request)
+    result = await _social(request).operations.reschedule(workspace_id, post_id, payload)
+    await _audit(request, "publishing.rescheduled", post_id=post_id)
+    return result
+
+
 @router.post("/posts/{post_id}/cancel", response_model=SocialPostView)
 async def cancel_post(request: Request, post_id: str) -> SocialPostView:
     workspace_id, _ = _identity(request)
     result = await _social(request).publishing.cancel(workspace_id, post_id)
     await _audit(request, "SOCIAL_POST_CANCELLED", post_id=post_id)
+    await _audit(request, "publishing.cancelled", post_id=post_id)
+    return result
+
+
+@router.get("/calendar", response_model=PublishingCalendarView)
+async def publishing_calendar(
+    request: Request,
+    starts_at: datetime = Query(),
+    ends_at: datetime = Query(),
+    offset: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=500),
+) -> PublishingCalendarView:
+    workspace_id, _ = _identity(request)
+    return await _social(request).operations.calendar(
+        workspace_id,
+        starts_at=starts_at,
+        ends_at=ends_at,
+        offset=offset,
+        limit=limit,
+    )
+
+
+@router.get("/publishing-context", response_model=PublishingContextView)
+async def publishing_context(request: Request) -> PublishingContextView:
+    workspace_id, _ = _identity(request)
+    return PublishingContextView(
+        timezone=await _social(request).operations.workspace_timezone(workspace_id)
+    )
+
+
+@router.get("/queue", response_model=PublishingQueueView)
+async def publishing_queue(
+    request: Request,
+    offset: int = Query(default=0, ge=0),
+    limit: int = Query(default=50, ge=1, le=200),
+    queue_status: str | None = Query(default=None, alias="status", max_length=32),
+    provider: str | None = Query(default=None, max_length=32),
+    account_id: str | None = Query(default=None, max_length=120),
+    project_id: str | None = Query(default=None, max_length=36),
+    search: str | None = Query(default=None, max_length=200),
+) -> PublishingQueueView:
+    workspace_id, _ = _identity(request)
+    return await _social(request).operations.queue(
+        workspace_id,
+        offset=offset,
+        limit=limit,
+        status=queue_status,
+        provider=provider,
+        account_id=account_id,
+        project_id=project_id,
+        search=search,
+    )
+
+
+@router.post(
+    "/bulk",
+    response_model=PublishingBatchView,
+    status_code=status.HTTP_202_ACCEPTED,
+)
+async def create_publishing_batch(
+    request: Request,
+    payload: PublishingBulkRequest,
+    idempotency_key: str = Header(alias="Idempotency-Key", min_length=8, max_length=255),
+) -> PublishingBatchView:
+    workspace_id, user_id = _identity(request)
+    result = await _social(request).operations.create_batch(
+        workspace_id,
+        user_id,
+        payload,
+        idempotency_key=idempotency_key,
+    )
+    await _audit(request, "publishing.bulk_started")
+    return result
+
+
+@router.post(
+    "/posts/{post_id}/targets/{target_id}/retry",
+    response_model=SocialJobView,
+    status_code=status.HTTP_202_ACCEPTED,
+)
+async def retry_post_target(
+    request: Request,
+    post_id: str,
+    target_id: str,
+    idempotency_key: str = Header(alias="Idempotency-Key", min_length=8, max_length=255),
+) -> SocialJobView:
+    workspace_id, _ = _identity(request)
+    result = await _social(request).publishing.retry_target(
+        workspace_id,
+        post_id,
+        target_id,
+        idempotency_key=idempotency_key,
+    )
+    await _audit(
+        request,
+        "SOCIAL_TARGET_RETRY_QUEUED",
+        provider=result.provider.value if result.provider else None,
+        post_id=post_id,
+        job_id=result.id,
+    )
     return result
 
 
@@ -294,9 +494,7 @@ async def list_jobs(
     limit: int = Query(default=100, ge=1, le=500),
 ) -> list[SocialJobView]:
     workspace_id, _ = _identity(request)
-    return await _social(request).jobs.list(
-        workspace_id, offset=offset, limit=limit
-    )
+    return await _social(request).jobs.list(workspace_id, offset=offset, limit=limit)
 
 
 @router.get("/jobs/{job_id}", response_model=SocialJobView)

app/brand/__init__.py

@@ -0,0 +1,2 @@
+"""Workspace-scoped brand kits and brand governance."""
+

app/brand/api.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+from uuid import UUID
+from fastapi import APIRouter, Request, Response, status
+from app.brand.schemas import BrandKitCreate, BrandKitResponse
+from app.security.errors import ForbiddenError
+
+router = APIRouter(prefix="/v1/brand", tags=["brand"])
+
+def _identity(request: Request) -> tuple[str, str]:
+    context = request.state.auth
+    if not context.workspace_id or not context.user_id:
+        raise ForbiddenError
+    return context.workspace_id, context.user_id
+
+@router.post("", response_model=BrandKitResponse, status_code=status.HTTP_201_CREATED)
+async def create_brand_kit(request: Request, payload: BrandKitCreate) -> BrandKitResponse:
+    workspace_id, user_id = _identity(request)
+    kit, version = await request.app.state.container.brand_kits.create_brand_kit(
+        workspace_id=workspace_id,
+        name=payload.name,
+        description=payload.description,
+        user_id=user_id,
+    )
+    latest = await request.app.state.container.brand_kits.get_brand_kit_version(
+        workspace_id=workspace_id,
+        brand_kit_id=kit.id,
+        user_id=user_id,
+    )
+    return BrandKitResponse(
+        id=kit.id,
+        name=kit.name,
+        description=kit.description,
+        status=kit.status,
+        is_default=kit.is_default,
+        active_version_id=latest.id,
+        created_at=kit.created_at.isoformat(),
+        updated_at=kit.updated_at.isoformat(),
+    )
+
+@router.get("", response_model=list[BrandKitResponse])
+async def list_brand_kits(request: Request) -> list[BrandKitResponse]:
+    workspace_id, user_id = _identity(request)
+    kits = await request.app.state.container.brand_kits.list_brand_kits(
+        workspace_id=workspace_id,
+        user_id=user_id,
+    )
+    response: list[BrandKitResponse] = []
+    for kit in kits:
+        try:
+            latest = await request.app.state.container.brand_kits.get_brand_kit_version(
+                workspace_id=workspace_id,
+                brand_kit_id=kit.id,
+                user_id=user_id,
+            )
+            active_version_id = latest.id
+        except Exception:
+            active_version_id = kit.active_version_id
+        response.append(BrandKitResponse(
+            id=kit.id,
+            name=kit.name,
+            description=kit.description,
+            status=kit.status,
+            is_default=kit.is_default,
+            active_version_id=active_version_id,
+            created_at=kit.created_at.isoformat(),
+            updated_at=kit.updated_at.isoformat(),
+        ))
+    return response
+
+@router.patch("/{brand_kit_id}", response_model=BrandKitResponse)
+async def update_brand_kit(request: Request, brand_kit_id: UUID, payload: BrandKitCreate) -> BrandKitResponse:
+    workspace_id, user_id = _identity(request)
+    version = await request.app.state.container.brand_kits.update_brand_kit(
+        workspace_id=workspace_id,
+        brand_kit_id=str(brand_kit_id),
+        user_id=user_id,
+        data=payload.initial_version,
+    )
+    kit = await request.app.state.container.brand_kits.get_brand_kit(workspace_id, str(brand_kit_id), user_id=user_id)
+    return BrandKitResponse(
+        id=kit.id,
+        name=kit.name,
+        description=kit.description,
+        status=kit.status,
+        is_default=kit.is_default,
+        active_version_id=version.id,
+        created_at=kit.created_at.isoformat(),
+        updated_at=kit.updated_at.isoformat(),
+    )
+
+@router.delete("/{brand_kit_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_brand_kit(request: Request, brand_kit_id: UUID) -> Response:
+    workspace_id, user_id = _identity(request)
+    await request.app.state.container.brand_kits.delete_brand_kit(
+        workspace_id=workspace_id,
+        brand_kit_id=str(brand_kit_id),
+        user_id=user_id,
+    )
+    return Response(status_code=status.HTTP_204_NO_CONTENT)

app/brand/capabilities.py

@@ -0,0 +1,26 @@
+from app.brand.schemas import BrandCapabilities
+
+
+def brand_capabilities(*, watermark_rendering: bool = False) -> BrandCapabilities:
+    return BrandCapabilities(
+        watermark_rendering="available" if watermark_rendering else "configuration_only",
+        supported_asset_roles=[
+            "logo_primary",
+            "logo_secondary",
+            "watermark",
+            "favicon",
+            "social_avatar",
+            "social_cover",
+        ],
+        supported_providers=[
+            "facebook",
+            "instagram",
+            "tiktok",
+            "x",
+            "youtube",
+            "linkedin",
+            "telegram",
+            "whatsapp",
+        ],
+    )
+

app/brand/errors.py

@@ -0,0 +1,9 @@
+from app.core.exceptions import MediaAPIError
+
+class BrandKitNotFoundError(MediaAPIError):
+    code = "BRAND_KIT_NOT_FOUND"
+    status_code = 404
+
+class BrandKitValidationError(MediaAPIError):
+    code = "INVALID_BRAND_KIT"
+    status_code = 422

app/brand/models.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import uuid4
+
+from sqlalchemy import (
+    JSON,
+    Boolean,
+    CheckConstraint,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    Numeric,
+    String,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.security.models import Base, utcnow
+
+
+class BrandKit(Base):
+    __tablename__ = "brand_kits"
+    __table_args__ = (
+        CheckConstraint("status in ('active','archived')", name="ck_brand_kits_status"),
+        Index("ix_brand_kits_workspace_updated", "workspace_id", "updated_at"),
+        Index("ix_brand_kits_workspace_default", "workspace_id", "is_default"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    workspace_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("workspaces.id", ondelete="RESTRICT"), nullable=False
+    )
+    name: Mapped[str] = mapped_column(String(200), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text)
+    status: Mapped[str] = mapped_column(String(16), nullable=False, default="active")
+    is_default: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    active_version_id: Mapped[str | None] = mapped_column(String(36))
+    created_by: Mapped[str] = mapped_column(
+        String(36), ForeignKey("users.id", ondelete="RESTRICT"), nullable=False
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=utcnow
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow
+    )
+
+
+class BrandKitVersion(Base):
+    __tablename__ = "brand_kit_versions"
+    __table_args__ = (
+        UniqueConstraint("brand_kit_id", "version_number", name="uq_brand_kit_version"),
+        CheckConstraint("status in ('draft','published','archived')", name="ck_brand_version_status"),
+        Index("ix_brand_versions_kit_created", "brand_kit_id", "created_at"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    workspace_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("workspaces.id", ondelete="RESTRICT"), nullable=False
+    )
+    brand_kit_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("brand_kits.id", ondelete="CASCADE"), nullable=False
+    )
+    version_number: Mapped[int] = mapped_column(Integer, nullable=False)
+    status: Mapped[str] = mapped_column(String(16), nullable=False, default="draft")
+    logo_asset_id: Mapped[str | None] = mapped_column(String(36), ForeignKey("media_assets.id", ondelete="SET NULL"))
+    favicon_asset_id: Mapped[str | None] = mapped_column(String(36), ForeignKey("media_assets.id", ondelete="SET NULL"))
+    primary_color: Mapped[str | None] = mapped_column(String(32))
+    secondary_color: Mapped[str | None] = mapped_column(String(32))
+    accent_color: Mapped[str | None] = mapped_column(String(32))
+    background_color: Mapped[str | None] = mapped_column(String(32))
+    text_color: Mapped[str | None] = mapped_column(String(32))
+    font_family_primary: Mapped[str | None] = mapped_column(String(255))
+    font_family_secondary: Mapped[str | None] = mapped_column(String(255))
+    heading_font: Mapped[str | None] = mapped_column(String(255))
+    body_font: Mapped[str | None] = mapped_column(String(255))
+    voice_style: Mapped[str | None] = mapped_column(String(255))
+    tone: Mapped[str | None] = mapped_column(String(255))
+    default_cta: Mapped[str | None] = mapped_column(String(255))
+    default_hashtags: Mapped[dict[str, object]] = mapped_column(JSON, nullable=False, default=list)
+    watermark_asset_id: Mapped[str | None] = mapped_column(String(36), ForeignKey("media_assets.id", ondelete="SET NULL"))
+    watermark_position: Mapped[str | None] = mapped_column(String(32))
+    watermark_opacity: Mapped[float | None] = mapped_column(Numeric(precision=3, scale=2))
+    metadata: Mapped[dict[str, object]] = mapped_column(JSON, nullable=False, default=dict)
+    created_by: Mapped[str] = mapped_column(
+        String(36), ForeignKey("users.id", ondelete="RESTRICT"), nullable=False
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=utcnow
+    )
+    published_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class BrandKitAsset(Base):
+    __tablename__ = "brand_kit_assets"
+    __table_args__ = (
+        UniqueConstraint("brand_kit_version_id", "role", name="uq_brand_asset_role"),
+        Index("ix_brand_assets_workspace_asset", "workspace_id", "asset_id"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    workspace_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("workspaces.id", ondelete="RESTRICT"), nullable=False
+    )
+    brand_kit_version_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("brand_kit_versions.id", ondelete="CASCADE"), nullable=False
+    )
+    asset_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("media_assets.id", ondelete="RESTRICT"), nullable=False
+    )
+    role: Mapped[str] = mapped_column(String(32), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=utcnow
+    )
+
+
+class BrandKitPlatformSetting(Base):
+    __tablename__ = "brand_kit_platform_settings"
+    __table_args__ = (
+        UniqueConstraint(
+            "brand_kit_version_id", "provider", name="uq_brand_platform_setting"
+        ),
+        Index("ix_brand_platform_settings_workspace", "workspace_id"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    workspace_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("workspaces.id", ondelete="RESTRICT"), nullable=False
+    )
+    brand_kit_version_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("brand_kit_versions.id", ondelete="CASCADE"), nullable=False
+    )
+    provider: Mapped[str] = mapped_column(String(32), nullable=False)
+    settings_json: Mapped[dict[str, object]] = mapped_column(
+        "settings", JSON, nullable=False, default=dict
+    )
+
+
+class BrandGovernanceSetting(Base):
+    __tablename__ = "brand_governance_settings"
+    __table_args__ = (UniqueConstraint("workspace_id", name="uq_brand_governance_workspace"),)
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    workspace_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("workspaces.id", ondelete="CASCADE"), nullable=False
+    )
+    require_brand_kit_for_publish: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False
+    )
+    require_published_brand_version: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False
+    )
+    allow_user_override_brand_defaults: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True
+    )
+    updated_by: Mapped[str] = mapped_column(
+        String(36), ForeignKey("users.id", ondelete="RESTRICT"), nullable=False
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow
+    )
+

app/brand/models/__init__.py

@@ -0,0 +1,3 @@
+from app.brand.models.brand import BrandKit, BrandKitVersion
+
+__all__ = ["BrandKit", "BrandKitVersion"]

app/brand/models/brand.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+from datetime import datetime
+from uuid import uuid4
+from sqlalchemy import String, JSON, DateTime, Integer, Index, ForeignKey, UniqueConstraint, Text, Numeric
+from sqlalchemy.orm import Mapped, mapped_column
+from app.security.models import Base, utcnow
+
+class BrandKit(Base):
+    __tablename__ = "brand_kits"
+    
+    __table_args__ = (
+        Index("ix_brand_kits_workspace_updated", "workspace_id", "updated_at"),
+        UniqueConstraint("workspace_id", "name", name="uq_brand_kits_workspace_name"),
+    )
+    
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    workspace_id: Mapped[str] = mapped_column(String(36), ForeignKey("workspaces.id", ondelete="CASCADE"), nullable=False)
+    created_by: Mapped[str] = mapped_column(String(36), ForeignKey("users.id", ondelete="RESTRICT"), nullable=False)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text)
+    status: Mapped[str] = mapped_column(String(20), nullable=False, default="draft") # draft, published, archived
+    active_version_id: Mapped[str | None] = mapped_column(String(36), ForeignKey("brand_kit_versions.id", ondelete="SET NULL"))
+    
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow)
+    archived_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+class BrandKitVersion(Base):
+    __tablename__ = "brand_kit_versions"
+    
+    __table_args__ = (
+        UniqueConstraint("brand_kit_id", "version_number", name="uq_brand_kit_version"),
+        Index("ix_brand_versions_kit_created", "brand_kit_id", "version_number"),
+    )
+    
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    brand_kit_id: Mapped[str] = mapped_column(String(36), ForeignKey("brand_kits.id", ondelete="CASCADE"), nullable=False)
+    version_number: Mapped[int] = mapped_column(Integer, nullable=False)
+    status: Mapped[str] = mapped_column(String(20), nullable=False, default="draft")
+    
+    # Branding Fields
+    logo_asset_id: Mapped[str | None] = mapped_column(String(36), ForeignKey("media_assets.id", ondelete="SET NULL"))
+    favicon_asset_id: Mapped[str | None] = mapped_column(String(36), ForeignKey("media_assets.id", ondelete="SET NULL"))
+    primary_color: Mapped[str | None] = mapped_column(String(7))
+    secondary_color: Mapped[str | None] = mapped_column(String(7))
+    accent_color: Mapped[str | None] = mapped_column(String(7))
+    background_color: Mapped[str | None] = mapped_column(String(7))
+    text_color: Mapped[str | None] = mapped_column(String(7))
+    font_family_primary: Mapped[str | None] = mapped_column(String(100))
+    font_family_secondary: Mapped[str | None] = mapped_column(String(100))
+    heading_font: Mapped[str | None] = mapped_column(String(100))
+    body_font: Mapped[str | None] = mapped_column(String(100))
+    voice_style: Mapped[str | None] = mapped_column(String(50))
+    tone: Mapped[str | None] = mapped_column(String(50))
+    default_cta: Mapped[str | None] = mapped_column(String(100))
+    default_hashtags: Mapped[dict[str, object]] = mapped_column(JSON, nullable=False, default=dict)
+    watermark_asset_id: Mapped[str | None] = mapped_column(String(36), ForeignKey("media_assets.id", ondelete="SET NULL"))
+    watermark_position: Mapped[str | None] = mapped_column(String(20))
+    watermark_opacity: Mapped[float | None] = mapped_column(Numeric(precision=3, scale=2))
+    metadata: Mapped[dict[str, object]] = mapped_column(JSON, nullable=False, default=dict)
+    
+    created_by: Mapped[str] = mapped_column(String(36), ForeignKey("users.id", ondelete="RESTRICT"), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow)
+    published_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))

app/brand/repositories/brand_repository.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+from sqlalchemy import select, func
+from app.brand.models.brand import BrandKit, BrandKitVersion
+from app.brand.errors import BrandKitNotFoundError
+from app.security.database import SecurityDatabase
+from app.security.models import utcnow
+
+class BrandKitRepository:
+    def __init__(self, database: SecurityDatabase) -> None:
+        self.database = database
+        
+    def _map_data_to_version_args(self, data: dict[str, object]) -> dict[str, object]:
+        return {
+            "logo_asset_id": data.get("logo_asset_id"),
+            "favicon_asset_id": data.get("favicon_asset_id"),
+            "primary_color": data.get("primary_color"),
+            "secondary_color": data.get("secondary_color"),
+            "accent_color": data.get("accent_color"),
+            "background_color": data.get("background_color"),
+            "text_color": data.get("text_color"),
+            "font_family_primary": data.get("font_family_primary"),
+            "font_family_secondary": data.get("font_family_secondary"),
+            "heading_font": data.get("heading_font"),
+            "body_font": data.get("body_font"),
+            "voice_style": data.get("voice_style"),
+            "tone": data.get("tone"),
+            "default_cta": data.get("default_cta"),
+            "default_hashtags": data.get("default_hashtags", {}),
+            "watermark_asset_id": data.get("watermark_asset_id"),
+            "watermark_position": data.get("watermark_position"),
+            "watermark_opacity": data.get("watermark_opacity"),
+            "metadata": data.get("metadata", {}),
+        }
+        
+    async def create(self, workspace_id: str, name: str, data: dict[str, object], *, user_id: str) -> tuple[BrandKit, BrandKitVersion]:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            kit = BrandKit(workspace_id=workspace_id, name=name)
+            session.add(kit)
+            await session.flush() # Populate ID
+            
+            version = BrandKitVersion(
+                brand_kit_id=kit.id, 
+                version_number=1, 
+                created_by=user_id,
+                **self._map_data_to_version_args(data)
+            )
+            session.add(version)
+            
+            await session.commit()
+            await session.refresh(kit)
+            await session.refresh(version)
+            return kit, version
+            
+    async def get(self, workspace_id: str, brand_kit_id: str, *, user_id: str) -> BrandKit:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            kit = await session.scalar(
+                select(BrandKit).where(
+                    BrandKit.id == brand_kit_id,
+                    BrandKit.workspace_id == workspace_id,
+                )
+            )
+            if kit is None:
+                raise BrandKitNotFoundError(f"Brand Kit {brand_kit_id} not found.")
+            return kit
+
+    async def list(self, workspace_id: str, *, user_id: str) -> list[BrandKit]:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            return list((await session.scalars(
+                select(BrandKit).where(BrandKit.workspace_id == workspace_id)
+            )).all())
+            
+    async def get_latest_version(self, workspace_id: str, brand_kit_id: str, *, user_id: str) -> BrandKitVersion:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            version = await session.scalar(
+                select(BrandKitVersion)
+                .join(BrandKit)
+                .where(BrandKit.id == brand_kit_id, BrandKit.workspace_id == workspace_id)
+                .order_by(BrandKitVersion.version_number.desc())
+                .limit(1)
+            )
+            if version is None:
+                raise BrandKitNotFoundError(f"No version found for Brand Kit {brand_kit_id}.")
+            return version
+
+    async def create_version(self, workspace_id: str, brand_kit_id: str, data: dict[str, object], *, user_id: str) -> BrandKitVersion:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            # Check existence and lock
+            kit = await session.scalar(
+                select(BrandKit).where(
+                    BrandKit.id == brand_kit_id,
+                    BrandKit.workspace_id == workspace_id,
+                ).with_for_update()
+            )
+            if kit is None:
+                raise BrandKitNotFoundError(f"Brand Kit {brand_kit_id} not found.")
+                
+            # Get latest version number
+            latest_version = await session.scalar(
+                select(func.max(BrandKitVersion.version_number))
+                .where(BrandKitVersion.brand_kit_id == brand_kit_id)
+            )
+            
+            new_version = BrandKitVersion(
+                brand_kit_id=brand_kit_id, 
+                version_number=(latest_version or 0) + 1, 
+                created_by=user_id,
+                **self._map_data_to_version_args(data)
+            )
+            session.add(new_version)
+            kit.updated_at = utcnow()
+            await session.commit()
+            await session.refresh(new_version)
+            return new_version
+
+    async def delete(self, workspace_id: str, brand_kit_id: str, *, user_id: str) -> None:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            kit = await session.scalar(
+                select(BrandKit).where(
+                    BrandKit.id == brand_kit_id,
+                    BrandKit.workspace_id == workspace_id,
+                ).with_for_update()
+            )
+            if kit is None:
+                raise BrandKitNotFoundError(f"Brand Kit {brand_kit_id} not found.")
+            await session.delete(kit)
+            await session.commit()

app/brand/repository.py

@@ -0,0 +1,603 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from sqlalchemy import delete, func, or_, select, update
+from sqlalchemy.exc import IntegrityError
+
+from app.brand.errors import (
+    BrandConflictError,
+    BrandImmutableError,
+    BrandNotFoundError,
+    BrandVersionNotFoundError,
+)
+from app.brand.models import (
+    BrandGovernanceSetting,
+    BrandKit,
+    BrandKitAsset,
+    BrandKitPlatformSetting,
+    BrandKitVersion,
+)
+from app.projects.models import Project
+from app.security.database import SecurityDatabase
+from app.security.models import CanonicalMediaAsset
+
+
+class BrandRepository:
+    def __init__(self, database: SecurityDatabase) -> None:
+        self.database = database
+
+    async def list(
+        self,
+        workspace_id: str,
+        *,
+        user_id: str,
+        search: str | None,
+        status: str,
+        offset: int,
+        limit: int,
+    ) -> tuple[list[BrandKit], int]:
+        predicates = [
+            BrandKit.workspace_id == workspace_id,
+            BrandKit.status == status,
+        ]
+        if search:
+            term = search.casefold()
+            predicates.append(
+                or_(
+                    func.lower(BrandKit.name).contains(term, autoescape=True),
+                    func.lower(BrandKit.description).contains(term, autoescape=True),
+                )
+            )
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            total = int(
+                await session.scalar(
+                    select(func.count()).select_from(BrandKit).where(*predicates)
+                )
+                or 0
+            )
+            items = list(
+                (
+                    await session.scalars(
+                        select(BrandKit)
+                        .where(*predicates)
+                        .order_by(BrandKit.is_default.desc(), BrandKit.updated_at.desc())
+                        .offset(offset)
+                        .limit(limit)
+                    )
+                ).all()
+            )
+        return items, total
+
+    async def create(
+        self, kit: BrandKit, version: BrandKitVersion, *, user_id: str
+    ) -> tuple[BrandKit, BrandKitVersion]:
+        async with self.database.tenant_session(
+            workspace_id=kit.workspace_id, user_id=user_id
+        ) as session:
+            if kit.is_default:
+                await session.execute(
+                    update(BrandKit)
+                    .where(BrandKit.workspace_id == kit.workspace_id)
+                    .values(is_default=False)
+                )
+            session.add(kit)
+            await session.flush()
+            version.brand_kit_id = kit.id
+            session.add(version)
+            try:
+                await session.commit()
+            except IntegrityError as exc:
+                await session.rollback()
+                raise BrandConflictError("Brand kit creation conflicted with existing data.") from exc
+            await session.refresh(kit)
+            await session.refresh(version)
+            return kit, version
+
+    async def get(
+        self, workspace_id: str, brand_kit_id: str, *, user_id: str, mutable: bool = False
+    ) -> BrandKit:
+        query = select(BrandKit).where(
+            BrandKit.id == brand_kit_id,
+            BrandKit.workspace_id == workspace_id,
+        )
+        if mutable:
+            query = query.with_for_update()
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            kit = await session.scalar(query)
+            if kit is None:
+                raise BrandNotFoundError("Brand kit was not found in this workspace.")
+            return kit
+
+    async def update(
+        self,
+        workspace_id: str,
+        brand_kit_id: str,
+        *,
+        user_id: str,
+        fields: dict[str, object],
+    ) -> BrandKit:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            kit = await session.scalar(
+                select(BrandKit)
+                .where(
+                    BrandKit.id == brand_kit_id,
+                    BrandKit.workspace_id == workspace_id,
+                )
+                .with_for_update()
+            )
+            if kit is None:
+                raise BrandNotFoundError("Brand kit was not found in this workspace.")
+            for key, value in fields.items():
+                setattr(kit, key, value)
+            kit.updated_at = datetime.now(timezone.utc)
+            await session.commit()
+            await session.refresh(kit)
+            return kit
+
+    async def archive(
+        self, workspace_id: str, brand_kit_id: str, *, user_id: str
+    ) -> BrandKit:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            kit = await session.scalar(
+                select(BrandKit)
+                .where(
+                    BrandKit.id == brand_kit_id,
+                    BrandKit.workspace_id == workspace_id,
+                )
+                .with_for_update()
+            )
+            if kit is None:
+                raise BrandNotFoundError("Brand kit was not found in this workspace.")
+            if kit.is_default:
+                raise BrandConflictError("The default brand kit must be replaced before archiving.")
+            kit.status = "archived"
+            kit.updated_at = datetime.now(timezone.utc)
+            await session.commit()
+            await session.refresh(kit)
+            return kit
+
+    async def set_default(
+        self, workspace_id: str, brand_kit_id: str, *, user_id: str
+    ) -> BrandKit:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            kit = await session.scalar(
+                select(BrandKit)
+                .where(
+                    BrandKit.id == brand_kit_id,
+                    BrandKit.workspace_id == workspace_id,
+                    BrandKit.status == "active",
+                )
+                .with_for_update()
+            )
+            if kit is None:
+                raise BrandNotFoundError("Active brand kit was not found in this workspace.")
+            await session.execute(
+                update(BrandKit)
+                .where(BrandKit.workspace_id == workspace_id)
+                .values(is_default=False)
+            )
+            kit.is_default = True
+            kit.updated_at = datetime.now(timezone.utc)
+            await session.commit()
+            await session.refresh(kit)
+            return kit
+
+    async def versions(
+        self, workspace_id: str, brand_kit_id: str, *, user_id: str
+    ) -> list[BrandKitVersion]:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            if not await session.scalar(
+                select(BrandKit.id).where(
+                    BrandKit.id == brand_kit_id,
+                    BrandKit.workspace_id == workspace_id,
+                )
+            ):
+                raise BrandNotFoundError("Brand kit was not found in this workspace.")
+            return list(
+                (
+                    await session.scalars(
+                        select(BrandKitVersion)
+                        .where(
+                            BrandKitVersion.workspace_id == workspace_id,
+                            BrandKitVersion.brand_kit_id == brand_kit_id,
+                        )
+                        .order_by(BrandKitVersion.version_number.desc())
+                    )
+                ).all()
+            )
+
+    async def version(
+        self,
+        workspace_id: str,
+        brand_kit_id: str,
+        version_id: str,
+        *,
+        user_id: str,
+    ) -> BrandKitVersion:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            item = await session.scalar(
+                select(BrandKitVersion).where(
+                    BrandKitVersion.id == version_id,
+                    BrandKitVersion.brand_kit_id == brand_kit_id,
+                    BrandKitVersion.workspace_id == workspace_id,
+                )
+            )
+            if item is None:
+                raise BrandVersionNotFoundError(
+                    "Brand kit version was not found in this workspace."
+                )
+            return item
+
+    async def create_version(
+        self, version: BrandKitVersion, *, user_id: str
+    ) -> BrandKitVersion:
+        async with self.database.tenant_session(
+            workspace_id=version.workspace_id, user_id=user_id
+        ) as session:
+            kit = await session.scalar(
+                select(BrandKit)
+                .where(
+                    BrandKit.id == version.brand_kit_id,
+                    BrandKit.workspace_id == version.workspace_id,
+                    BrandKit.status == "active",
+                )
+                .with_for_update()
+            )
+            if kit is None:
+                raise BrandNotFoundError("Active brand kit was not found in this workspace.")
+            version.version_number = (
+                int(
+                    await session.scalar(
+                        select(func.max(BrandKitVersion.version_number)).where(
+                            BrandKitVersion.brand_kit_id == version.brand_kit_id
+                        )
+                    )
+                    or 0
+                )
+                + 1
+            )
+            session.add(version)
+            await session.commit()
+            await session.refresh(version)
+            return version
+
+    async def update_version(
+        self,
+        workspace_id: str,
+        brand_kit_id: str,
+        version_id: str,
+        *,
+        user_id: str,
+        fields: dict[str, object],
+    ) -> BrandKitVersion:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            version = await session.scalar(
+                select(BrandKitVersion)
+                .where(
+                    BrandKitVersion.id == version_id,
+                    BrandKitVersion.brand_kit_id == brand_kit_id,
+                    BrandKitVersion.workspace_id == workspace_id,
+                )
+                .with_for_update()
+            )
+            if version is None:
+                raise BrandVersionNotFoundError(
+                    "Brand kit version was not found in this workspace."
+                )
+            if version.status != "draft":
+                raise BrandImmutableError("Published or archived brand versions are immutable.")
+            for key, value in fields.items():
+                setattr(version, key, value)
+            await session.commit()
+            await session.refresh(version)
+            return version
+
+    async def publish_version(
+        self, workspace_id: str, brand_kit_id: str, version_id: str, *, user_id: str
+    ) -> tuple[BrandKit, BrandKitVersion]:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            kit = await session.scalar(
+                select(BrandKit)
+                .where(
+                    BrandKit.id == brand_kit_id,
+                    BrandKit.workspace_id == workspace_id,
+                    BrandKit.status == "active",
+                )
+                .with_for_update()
+            )
+            version = await session.scalar(
+                select(BrandKitVersion)
+                .where(
+                    BrandKitVersion.id == version_id,
+                    BrandKitVersion.brand_kit_id == brand_kit_id,
+                    BrandKitVersion.workspace_id == workspace_id,
+                )
+                .with_for_update()
+            )
+            if kit is None:
+                raise BrandNotFoundError("Active brand kit was not found in this workspace.")
+            if version is None:
+                raise BrandVersionNotFoundError(
+                    "Brand kit version was not found in this workspace."
+                )
+            if version.status != "draft":
+                raise BrandConflictError("Only a draft brand version can be published.")
+            now = datetime.now(timezone.utc)
+            version.status = "published"
+            version.published_at = now
+            kit.active_version_id = version.id
+            kit.updated_at = now
+            await session.commit()
+            await session.refresh(kit)
+            await session.refresh(version)
+            return kit, version
+
+    async def archive_version(
+        self, workspace_id: str, brand_kit_id: str, version_id: str, *, user_id: str
+    ) -> BrandKitVersion:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            kit = await session.scalar(
+                select(BrandKit)
+                .where(
+                    BrandKit.id == brand_kit_id,
+                    BrandKit.workspace_id == workspace_id,
+                )
+                .with_for_update()
+            )
+            version = await session.scalar(
+                select(BrandKitVersion)
+                .where(
+                    BrandKitVersion.id == version_id,
+                    BrandKitVersion.brand_kit_id == brand_kit_id,
+                    BrandKitVersion.workspace_id == workspace_id,
+                )
+                .with_for_update()
+            )
+            if kit is None or version is None:
+                raise BrandVersionNotFoundError(
+                    "Brand kit version was not found in this workspace."
+                )
+            if kit.active_version_id == version.id:
+                raise BrandConflictError("The active published version cannot be archived.")
+            version.status = "archived"
+            await session.commit()
+            await session.refresh(version)
+            return version
+
+    async def replace_platform_settings(
+        self,
+        workspace_id: str,
+        version_id: str,
+        settings: list[BrandKitPlatformSetting],
+        *,
+        user_id: str,
+    ) -> None:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            version = await session.scalar(
+                select(BrandKitVersion)
+                .where(
+                    BrandKitVersion.id == version_id,
+                    BrandKitVersion.workspace_id == workspace_id,
+                )
+                .with_for_update()
+            )
+            if version is None:
+                raise BrandVersionNotFoundError("Brand kit version was not found.")
+            if version.status != "draft":
+                raise BrandImmutableError("Published or archived brand versions are immutable.")
+            await session.execute(
+                delete(BrandKitPlatformSetting).where(
+                    BrandKitPlatformSetting.brand_kit_version_id == version_id
+                )
+            )
+            session.add_all(settings)
+            await session.commit()
+
+    async def platform_settings(
+        self, workspace_id: str, version_id: str, *, user_id: str
+    ) -> list[BrandKitPlatformSetting]:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            return list(
+                (
+                    await session.scalars(
+                        select(BrandKitPlatformSetting).where(
+                            BrandKitPlatformSetting.workspace_id == workspace_id,
+                            BrandKitPlatformSetting.brand_kit_version_id == version_id,
+                        )
+                    )
+                ).all()
+            )
+
+    async def assets(
+        self, workspace_id: str, version_id: str, *, user_id: str
+    ) -> list[tuple[BrandKitAsset, CanonicalMediaAsset]]:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            rows = await session.execute(
+                select(BrandKitAsset, CanonicalMediaAsset)
+                .join(CanonicalMediaAsset, CanonicalMediaAsset.id == BrandKitAsset.asset_id)
+                .where(
+                    BrandKitAsset.workspace_id == workspace_id,
+                    BrandKitAsset.brand_kit_version_id == version_id,
+                    CanonicalMediaAsset.workspace_id == workspace_id,
+                )
+            )
+            return list(rows.all())
+
+    async def attach_asset(
+        self, association: BrandKitAsset, *, user_id: str
+    ) -> BrandKitAsset:
+        async with self.database.tenant_session(
+            workspace_id=association.workspace_id, user_id=user_id
+        ) as session:
+            version = await session.scalar(
+                select(BrandKitVersion)
+                .where(
+                    BrandKitVersion.id == association.brand_kit_version_id,
+                    BrandKitVersion.workspace_id == association.workspace_id,
+                )
+                .with_for_update()
+            )
+            if version is None:
+                raise BrandVersionNotFoundError("Brand kit version was not found.")
+            if version.status != "draft":
+                raise BrandImmutableError("Assets on a published brand version are immutable.")
+            existing = await session.scalar(
+                select(BrandKitAsset).where(
+                    BrandKitAsset.brand_kit_version_id
+                    == association.brand_kit_version_id,
+                    BrandKitAsset.role == association.role,
+                )
+            )
+            if existing:
+                existing.asset_id = association.asset_id
+                await session.commit()
+                await session.refresh(existing)
+                return existing
+            session.add(association)
+            await session.commit()
+            await session.refresh(association)
+            return association
+
+    async def detach_asset(
+        self,
+        workspace_id: str,
+        version_id: str,
+        asset_id: str,
+        *,
+        user_id: str,
+    ) -> None:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            version = await session.scalar(
+                select(BrandKitVersion)
+                .where(
+                    BrandKitVersion.id == version_id,
+                    BrandKitVersion.workspace_id == workspace_id,
+                )
+                .with_for_update()
+            )
+            if version is None:
+                raise BrandVersionNotFoundError("Brand kit version was not found.")
+            if version.status != "draft":
+                raise BrandImmutableError("Assets on a published brand version are immutable.")
+            result = await session.execute(
+                delete(BrandKitAsset).where(
+                    BrandKitAsset.workspace_id == workspace_id,
+                    BrandKitAsset.brand_kit_version_id == version_id,
+                    BrandKitAsset.asset_id == asset_id,
+                )
+            )
+            if not result.rowcount:
+                raise BrandVersionNotFoundError("Brand asset association was not found.")
+            await session.commit()
+
+    async def governance(
+        self, workspace_id: str, *, user_id: str
+    ) -> BrandGovernanceSetting | None:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            return await session.scalar(
+                select(BrandGovernanceSetting).where(
+                    BrandGovernanceSetting.workspace_id == workspace_id
+                )
+            )
+
+    async def set_governance(
+        self,
+        setting: BrandGovernanceSetting,
+        *,
+        user_id: str,
+    ) -> BrandGovernanceSetting:
+        async with self.database.tenant_session(
+            workspace_id=setting.workspace_id, user_id=user_id
+        ) as session:
+            existing = await session.scalar(
+                select(BrandGovernanceSetting)
+                .where(BrandGovernanceSetting.workspace_id == setting.workspace_id)
+                .with_for_update()
+            )
+            if existing is None:
+                session.add(setting)
+                existing = setting
+            else:
+                existing.require_brand_kit_for_publish = (
+                    setting.require_brand_kit_for_publish
+                )
+                existing.require_published_brand_version = (
+                    setting.require_published_brand_version
+                )
+                existing.allow_user_override_brand_defaults = (
+                    setting.allow_user_override_brand_defaults
+                )
+                existing.updated_by = setting.updated_by
+                existing.updated_at = datetime.now(timezone.utc)
+            await session.commit()
+            await session.refresh(existing)
+            return existing
+
+    async def apply_to_project(
+        self,
+        workspace_id: str,
+        brand_kit_id: str,
+        project_id: str,
+        *,
+        user_id: str,
+    ) -> Project:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            kit = await session.scalar(
+                select(BrandKit).where(
+                    BrandKit.id == brand_kit_id,
+                    BrandKit.workspace_id == workspace_id,
+                    BrandKit.status == "active",
+                )
+            )
+            project = await session.scalar(
+                select(Project)
+                .where(
+                    Project.id == project_id,
+                    Project.workspace_id == workspace_id,
+                    Project.status == "active",
+                )
+                .with_for_update()
+            )
+            if kit is None:
+                raise BrandNotFoundError("Active brand kit was not found in this workspace.")
+            if project is None:
+                raise BrandNotFoundError("Project was not found in this workspace.")
+            project.brand_kit_id = kit.id
+            project.updated_at = datetime.now(timezone.utc)
+            await session.commit()
+            await session.refresh(project)
+            return project
+

app/brand/schemas.py

@@ -0,0 +1,20 @@
+from pydantic import BaseModel, Field
+from datetime import datetime
+
+class BrandKitCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=255)
+    description: str | None = None
+    initial_version: dict[str, object]  # For now, keep as dict for simplicity, can be updated later
+
+class BrandKitResponse(BaseModel):
+    id: str
+    name: str
+    description: str | None
+    status: str
+    is_default: bool
+    active_version_id: str | None
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True

app/brand/service.py

@@ -0,0 +1,636 @@
+from __future__ import annotations
+
+from app.brand.capabilities import brand_capabilities
+from app.brand.errors import BrandAssetInvalidError, BrandGovernanceError
+from app.brand.models import (
+    BrandGovernanceSetting,
+    BrandKit,
+    BrandKitAsset,
+    BrandKitPlatformSetting,
+    BrandKitVersion,
+)
+from app.brand.repository import BrandRepository
+from app.brand.schemas import (
+    BrandApplyProject,
+    BrandAssetAttach,
+    BrandAssetView,
+    BrandCapabilities,
+    BrandGovernance,
+    BrandKitCreate,
+    BrandKitList,
+    BrandKitUpdate,
+    BrandKitView,
+    BrandVersionContent,
+    BrandVersionCreate,
+    BrandVersionUpdate,
+    BrandVersionView,
+)
+from app.brand.validation import validate_platform_settings
+from app.security.assets import CanonicalAssetNotFoundError, CanonicalAssetService
+from app.security.audit import AuditService
+
+
+class BrandService:
+    def __init__(
+        self,
+        repository: BrandRepository,
+        assets: CanonicalAssetService,
+        audit: AuditService,
+    ) -> None:
+        self.repository = repository
+        self.assets = assets
+        self.audit = audit
+
+    def capabilities(self) -> BrandCapabilities:
+        # Configuration is authoritative; the existing render compiler does not
+        # yet accept brand watermark instructions as a first-class contract.
+        return brand_capabilities(watermark_rendering=False)
+
+    async def list(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        search: str | None,
+        status: str,
+        offset: int,
+        limit: int,
+    ) -> BrandKitList:
+        kits, total = await self.repository.list(
+            workspace_id,
+            user_id=user_id,
+            search=search,
+            status=status,
+            offset=offset,
+            limit=limit,
+        )
+        return BrandKitList(
+            items=[await self._kit_view(kit, user_id=user_id) for kit in kits],
+            offset=offset,
+            limit=limit,
+            total=total,
+        )
+
+    async def get(
+        self, *, workspace_id: str, user_id: str, brand_kit_id: str
+    ) -> BrandKitView:
+        return await self._kit_view(
+            await self.repository.get(workspace_id, brand_kit_id, user_id=user_id),
+            user_id=user_id,
+        )
+
+    async def create(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        payload: BrandKitCreate,
+    ) -> BrandKitView:
+        self._validate_content(payload.initial_version)
+        kit, version = await self.repository.create(
+            BrandKit(
+                workspace_id=workspace_id,
+                name=payload.name,
+                description=payload.description,
+                is_default=payload.is_default,
+                created_by=user_id,
+            ),
+            self._version_model(
+                workspace_id, "", user_id, payload.initial_version, version=1
+            ),
+            user_id=user_id,
+        )
+        await self._replace_platform_settings(version, payload.initial_version, user_id)
+        await self._audit(
+            workspace_id,
+            user_id,
+            api_key_id,
+            request_id,
+            "brand.created",
+            kit.id,
+            {"is_default": kit.is_default},
+        )
+        await self._audit(
+            workspace_id,
+            user_id,
+            api_key_id,
+            request_id,
+            "brand.version_created",
+            kit.id,
+            {"version_id": version.id, "version": version.version},
+        )
+        return await self.get(
+            workspace_id=workspace_id, user_id=user_id, brand_kit_id=kit.id
+        )
+
+    async def update(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        brand_kit_id: str,
+        payload: BrandKitUpdate,
+    ) -> BrandKitView:
+        kit = await self.repository.update(
+            workspace_id,
+            brand_kit_id,
+            user_id=user_id,
+            fields=payload.model_dump(exclude_unset=True),
+        )
+        await self._audit(
+            workspace_id,
+            user_id,
+            api_key_id,
+            request_id,
+            "brand.updated",
+            kit.id,
+            {"fields": sorted(payload.model_fields_set)},
+        )
+        return await self._kit_view(kit, user_id=user_id)
+
+    async def delete(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        brand_kit_id: str,
+    ) -> None:
+        kit = await self.repository.archive(workspace_id, brand_kit_id, user_id=user_id)
+        await self._audit(
+            workspace_id,
+            user_id,
+            api_key_id,
+            request_id,
+            "brand.deleted",
+            kit.id,
+            {"disposition": "archived"},
+        )
+
+    async def versions(
+        self, *, workspace_id: str, user_id: str, brand_kit_id: str
+    ) -> list[BrandVersionView]:
+        return [
+            await self._version_view(item, user_id=user_id)
+            for item in await self.repository.versions(
+                workspace_id, brand_kit_id, user_id=user_id
+            )
+        ]
+
+    async def version(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        brand_kit_id: str,
+        version_id: str,
+    ) -> BrandVersionView:
+        return await self._version_view(
+            await self.repository.version(
+                workspace_id, brand_kit_id, version_id, user_id=user_id
+            ),
+            user_id=user_id,
+        )
+
+    async def create_version(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        brand_kit_id: str,
+        payload: BrandVersionCreate,
+    ) -> BrandVersionView:
+        content: BrandVersionContent = payload
+        if payload.source_version_id:
+            source = await self.version(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                brand_kit_id=brand_kit_id,
+                version_id=payload.source_version_id,
+            )
+            if not any(
+                field in payload.model_fields_set
+                for field in BrandVersionContent.model_fields
+            ):
+                content = BrandVersionContent.model_validate(
+                    source.model_dump(
+                        include=set(BrandVersionContent.model_fields), mode="json"
+                    )
+                )
+        self._validate_content(content)
+        version = await self.repository.create_version(
+            self._version_model(workspace_id, brand_kit_id, user_id, content, version=0),
+            user_id=user_id,
+        )
+        await self._replace_platform_settings(version, content, user_id)
+        await self._audit(
+            workspace_id,
+            user_id,
+            api_key_id,
+            request_id,
+            "brand.version_created",
+            brand_kit_id,
+            {"version_id": version.id, "version": version.version},
+        )
+        return await self._version_view(version, user_id=user_id)
+
+    async def update_version(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        brand_kit_id: str,
+        version_id: str,
+        payload: BrandVersionUpdate,
+    ) -> BrandVersionView:
+        self._validate_content(payload)
+        version = await self.repository.update_version(
+            workspace_id,
+            brand_kit_id,
+            version_id,
+            user_id=user_id,
+            fields=self._version_fields(payload),
+        )
+        await self._replace_platform_settings(version, payload, user_id)
+        await self._audit(
+            workspace_id,
+            user_id,
+            api_key_id,
+            request_id,
+            "brand.updated",
+            brand_kit_id,
+            {"version_id": version.id},
+        )
+        return await self._version_view(version, user_id=user_id)
+
+    async def publish_version(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        brand_kit_id: str,
+        version_id: str,
+    ) -> BrandKitView:
+        kit, version = await self.repository.publish_version(
+            workspace_id, brand_kit_id, version_id, user_id=user_id
+        )
+        await self._audit(
+            workspace_id,
+            user_id,
+            api_key_id,
+            request_id,
+            "brand.version_published",
+            kit.id,
+            {"version_id": version.id, "version": version.version},
+        )
+        return await self._kit_view(kit, user_id=user_id)
+
+    async def archive_version(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        brand_kit_id: str,
+        version_id: str,
+    ) -> BrandVersionView:
+        version = await self.repository.archive_version(
+            workspace_id, brand_kit_id, version_id, user_id=user_id
+        )
+        await self._audit(
+            workspace_id,
+            user_id,
+            api_key_id,
+            request_id,
+            "brand.version_archived",
+            brand_kit_id,
+            {"version_id": version.id, "version": version.version},
+        )
+        return await self._version_view(version, user_id=user_id)
+
+    async def set_default(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        brand_kit_id: str,
+    ) -> BrandKitView:
+        kit = await self.repository.set_default(
+            workspace_id, brand_kit_id, user_id=user_id
+        )
+        await self._audit(
+            workspace_id,
+            user_id,
+            api_key_id,
+            request_id,
+            "brand.default_changed",
+            kit.id,
+            {},
+        )
+        return await self._kit_view(kit, user_id=user_id)
+
+    async def attach_asset(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        brand_kit_id: str,
+        payload: BrandAssetAttach,
+    ) -> BrandAssetView:
+        version = await self.repository.version(
+            workspace_id, brand_kit_id, payload.version_id, user_id=user_id
+        )
+        if version.status != "draft":
+            raise BrandAssetInvalidError(
+                "Assets may only be changed on a draft brand version."
+            )
+        try:
+            asset = await self.assets.get_owned_by_id(
+                workspace_id=workspace_id, user_id=user_id, asset_id=payload.asset_id
+            )
+        except CanonicalAssetNotFoundError as exc:
+            raise BrandAssetInvalidError(
+                "Brand asset is not an owned canonical asset."
+            ) from exc
+        if not asset.mime_type.startswith("image/"):
+            raise BrandAssetInvalidError("Brand logo and watermark assets must be images.")
+        association = await self.repository.attach_asset(
+            BrandKitAsset(
+                workspace_id=workspace_id,
+                brand_kit_version_id=version.id,
+                asset_id=asset.id,
+                role=payload.role,
+            ),
+            user_id=user_id,
+        )
+        return BrandAssetView(
+            id=association.id,
+            version_id=version.id,
+            asset_id=asset.id,
+            role=payload.role,
+            mime_type=asset.mime_type,
+            filename=asset.filename,
+        )
+
+    async def detach_asset(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        brand_kit_id: str,
+        version_id: str,
+        asset_id: str,
+    ) -> None:
+        await self.repository.version(
+            workspace_id, brand_kit_id, version_id, user_id=user_id
+        )
+        await self.repository.detach_asset(
+            workspace_id, version_id, asset_id, user_id=user_id
+        )
+
+    async def governance(
+        self, *, workspace_id: str, user_id: str
+    ) -> BrandGovernance:
+        setting = await self.repository.governance(workspace_id, user_id=user_id)
+        return BrandGovernance.model_validate(setting, from_attributes=True) if setting else BrandGovernance()
+
+    async def set_governance(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        payload: BrandGovernance,
+    ) -> BrandGovernance:
+        setting = await self.repository.set_governance(
+            BrandGovernanceSetting(
+                workspace_id=workspace_id,
+                updated_by=user_id,
+                **payload.model_dump(),
+            ),
+            user_id=user_id,
+        )
+        await self._audit(
+            workspace_id,
+            user_id,
+            api_key_id,
+            request_id,
+            "brand.updated",
+            setting.id,
+            {"governance": True},
+        )
+        return BrandGovernance.model_validate(setting, from_attributes=True)
+
+    async def apply_to_project(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        brand_kit_id: str,
+        payload: BrandApplyProject,
+    ) -> BrandKitView:
+        await self.repository.apply_to_project(
+            workspace_id,
+            brand_kit_id,
+            payload.project_id,
+            user_id=user_id,
+        )
+        await self._audit(
+            workspace_id,
+            user_id,
+            api_key_id,
+            request_id,
+            "brand.applied_to_project",
+            brand_kit_id,
+            {"project_id": payload.project_id},
+        )
+        return await self.get(
+            workspace_id=workspace_id, user_id=user_id, brand_kit_id=brand_kit_id
+        )
+
+    async def validate_publish(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        project_id: str | None,
+        brand_kit_id: str | None,
+        brand_kit_version_id: str | None,
+    ) -> tuple[str | None, str | None]:
+        governance = await self.governance(workspace_id=workspace_id, user_id=user_id)
+        if governance.require_brand_kit_for_publish and not brand_kit_id:
+            raise BrandGovernanceError("A brand kit is required before publishing.")
+        if not brand_kit_id:
+            return None, None
+        kit = await self.repository.get(workspace_id, brand_kit_id, user_id=user_id)
+        selected_version = brand_kit_version_id or kit.active_version_id
+        if governance.require_published_brand_version and not selected_version:
+            raise BrandGovernanceError("A published brand version is required before publishing.")
+        if selected_version:
+            version = await self.repository.version(
+                workspace_id, kit.id, selected_version, user_id=user_id
+            )
+            if governance.require_published_brand_version and version.status != "published":
+                raise BrandGovernanceError("Publishing requires a published brand version.")
+        return kit.id, selected_version
+
+    @staticmethod
+    def _validate_content(content: BrandVersionContent) -> None:
+        for item in content.platform_settings:
+            validate_platform_settings(item.provider, item.settings)
+
+    @staticmethod
+    def _version_fields(content: BrandVersionContent) -> dict[str, object]:
+        return {
+            "colors_json": [item.model_dump(mode="json") for item in content.colors],
+            "typography_json": content.typography.model_dump(mode="json"),
+            "voice_json": content.voice.model_dump(mode="json"),
+            "ctas_json": content.ctas.model_dump(mode="json"),
+            "hashtags_json": content.hashtags.model_dump(mode="json"),
+            "watermark_json": content.watermark.model_dump(mode="json"),
+            "ai_guidance": content.ai_guidance,
+            "metadata_json": content.metadata,
+        }
+
+    def _version_model(
+        self,
+        workspace_id: str,
+        brand_kit_id: str,
+        user_id: str,
+        content: BrandVersionContent,
+        *,
+        version: int,
+    ) -> BrandKitVersion:
+        return BrandKitVersion(
+            workspace_id=workspace_id,
+            brand_kit_id=brand_kit_id,
+            version=version,
+            status="draft",
+            created_by=user_id,
+            **self._version_fields(content),
+        )
+
+    async def _replace_platform_settings(
+        self, version: BrandKitVersion, content: BrandVersionContent, user_id: str
+    ) -> None:
+        await self.repository.replace_platform_settings(
+            version.workspace_id,
+            version.id,
+            [
+                BrandKitPlatformSetting(
+                    workspace_id=version.workspace_id,
+                    brand_kit_version_id=version.id,
+                    provider=item.provider,
+                    settings_json=item.settings,
+                )
+                for item in content.platform_settings
+            ],
+            user_id=user_id,
+        )
+
+    async def _kit_view(self, kit: BrandKit, *, user_id: str) -> BrandKitView:
+        active = (
+            await self.repository.version(
+                kit.workspace_id,
+                kit.id,
+                kit.active_version_id,
+                user_id=user_id,
+            )
+            if kit.active_version_id
+            else None
+        )
+        return BrandKitView(
+            id=kit.id,
+            workspace_id=kit.workspace_id,
+            name=kit.name,
+            description=kit.description,
+            status=kit.status,
+            is_default=kit.is_default,
+            active_version_id=kit.active_version_id,
+            active_version=(
+                await self._version_view(active, user_id=user_id) if active else None
+            ),
+            created_by=kit.created_by,
+            created_at=kit.created_at,
+            updated_at=kit.updated_at,
+        )
+
+    async def _version_view(
+        self, version: BrandKitVersion, *, user_id: str
+    ) -> BrandVersionView:
+        settings = await self.repository.platform_settings(
+            version.workspace_id, version.id, user_id=user_id
+        )
+        assets = await self.repository.assets(
+            version.workspace_id, version.id, user_id=user_id
+        )
+        return BrandVersionView(
+            id=version.id,
+            brand_kit_id=version.brand_kit_id,
+            version=version.version,
+            status=version.status,
+            colors=version.colors_json,
+            typography=version.typography_json,
+            voice=version.voice_json,
+            ctas=version.ctas_json,
+            hashtags=version.hashtags_json,
+            watermark=version.watermark_json,
+            ai_guidance=version.ai_guidance,
+            platform_settings=[
+                {"provider": item.provider, "settings": item.settings_json}
+                for item in settings
+            ],
+            metadata=version.metadata_json,
+            assets=[
+                BrandAssetView(
+                    id=association.id,
+                    version_id=version.id,
+                    asset_id=asset.id,
+                    role=association.role,
+                    mime_type=asset.mime_type,
+                    filename=asset.filename,
+                )
+                for association, asset in assets
+            ],
+            created_by=version.created_by,
+            created_at=version.created_at,
+            published_at=version.published_at,
+        )
+
+    async def _audit(
+        self,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        event_type: str,
+        entity_id: str,
+        metadata: dict[str, object],
+    ) -> None:
+        await self.audit.record_event(
+            workspace_id=workspace_id,
+            user_id=user_id,
+            api_key_id=api_key_id,
+            request_id=request_id,
+            event_type=event_type,
+            entity_type="brand_kit",
+            entity_id=entity_id,
+            metadata=metadata,
+        )

app/brand/services/brand_service.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+from app.brand.models.brand import BrandKit, BrandKitVersion
+from app.brand.repositories.brand_repository import BrandKitRepository
+from app.security.assets import CanonicalAssetService
+from app.security.audit import AuditService
+
+class BrandKitService:
+    def __init__(self, repository: BrandKitRepository, assets: CanonicalAssetService, audit: AuditService) -> None:
+        self.repository = repository
+        self.assets = assets
+        self.audit = audit
+        
+    async def _validate_assets(self, workspace_id: str, data: dict[str, object]) -> None:
+        for asset_key in ["logo_asset_id", "favicon_asset_id", "watermark_asset_id"]:
+            asset_id = data.get(asset_key)
+            if asset_id:
+                asset = await self.assets.get_asset(workspace_id=workspace_id, asset_id=str(asset_id))
+                if not asset:
+                    raise ValueError(f"Asset {asset_id} not found or inaccessible in this workspace.")
+
+    async def create_brand_kit(self, workspace_id: str, name: str, data: dict[str, object], *, user_id: str) -> tuple[BrandKit, BrandKitVersion]:
+        await self._validate_assets(workspace_id, data)
+        kit, version = await self.repository.create(workspace_id, name, data, user_id=user_id)
+        await self.audit.log_event(
+            workspace_id=workspace_id,
+            actor_user_id=user_id,
+            event_type="brand_kit.created",
+            entity_type="brand_kit",
+            entity_id=kit.id,
+            metadata={"name": kit.name}
+        )
+        return kit, version
+        
+    async def get_brand_kit(self, workspace_id: str, brand_kit_id: str, *, user_id: str) -> BrandKit:
+        return await self.repository.get(workspace_id, brand_kit_id, user_id=user_id)
+        
+    async def list_brand_kits(self, workspace_id: str, *, user_id: str) -> list[BrandKit]:
+        return await self.repository.list(workspace_id, user_id=user_id)
+    
+    async def get_brand_kit_version(self, workspace_id: str, brand_kit_id: str, *, user_id: str) -> BrandKitVersion:
+        return await self.repository.get_latest_version(workspace_id, brand_kit_id, user_id=user_id)
+
+    async def update_brand_kit(self, workspace_id: str, brand_kit_id: str, *, user_id: str, data: dict[str, object]) -> BrandKitVersion:
+        await self._validate_assets(workspace_id, data)
+        version = await self.repository.create_version(workspace_id, brand_kit_id, data, user_id=user_id)
+        await self.audit.log_event(
+            workspace_id=workspace_id,
+            actor_user_id=user_id,
+            event_type="brand_kit.version_created",
+            entity_type="brand_kit_version",
+            entity_id=version.id,
+            metadata={"brand_kit_id": brand_kit_id, "version_number": version.version_number}
+        )
+        return version
+
+    async def delete_brand_kit(self, workspace_id: str, brand_kit_id: str, *, user_id: str) -> None:
+        await self.repository.delete(workspace_id, brand_kit_id, user_id=user_id)
+        await self.audit.log_event(
+            workspace_id=workspace_id,
+            actor_user_id=user_id,
+            event_type="brand_kit.archived",
+            entity_type="brand_kit",
+            entity_id=brand_kit_id
+        )

app/brand/services/validation_service.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+from typing import Any
+from app.brand.models.brand import BrandKitVersion
+
+class BrandKitValidationService:
+    def validate(self, version: BrandKitVersion) -> dict[str, Any]:
+        """
+        Deterministic validation service.
+        Returns a dict with 'valid' boolean and 'issues' list of dicts:
+        {'severity': 'error'|'warning', 'field': str, 'reason': str}
+        """
+        issues = []
+        
+        # Required assets check
+        if not version.logo_asset_id:
+            issues.append({'severity': 'error', 'field': 'logo_asset_id', 'reason': 'Primary logo is required.'})
+            
+        # Color completeness
+        if not version.primary_color:
+            issues.append({'severity': 'warning', 'field': 'primary_color', 'reason': 'Primary color is not set.'})
+            
+        # Font checks
+        if not version.font_family_primary:
+            issues.append({'severity': 'warning', 'field': 'font_family_primary', 'reason': 'Primary font is not set.'})
+            
+        return {
+            'valid': len([i for i in issues if i['severity'] == 'error']) == 0,
+            'issues': issues
+        }

app/brand/validation.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any
+
+from app.brand.errors import BrandValidationError
+
+_PLATFORM_FIELDS: dict[str, frozenset[str]] = {
+    "facebook": frozenset({"caption_style", "hashtags", "cta"}),
+    "instagram": frozenset({"caption_style", "hashtags", "cta", "first_comment"}),
+    "tiktok": frozenset({"caption_style", "hashtags", "cta"}),
+    "x": frozenset({"caption_style", "hashtags", "cta"}),
+    "youtube": frozenset({"title_pattern", "description", "tags", "cta"}),
+    "linkedin": frozenset({"post_style", "hashtags", "cta"}),
+    "telegram": frozenset({"caption_style", "cta"}),
+    "whatsapp": frozenset({"caption_style", "cta"}),
+}
+
+
+def validate_platform_settings(provider: str, settings: dict[str, Any]) -> None:
+    unsupported = set(settings) - _PLATFORM_FIELDS.get(provider, frozenset())
+    if unsupported:
+        raise BrandValidationError(
+            f"Unsupported {provider} brand defaults: {', '.join(sorted(unsupported))}."
+        )
+    for key, value in settings.items():
+        if isinstance(value, str) and len(value) > 4000:
+            raise BrandValidationError(f"{provider}.{key} exceeds the supported length.")
+        if isinstance(value, list) and len(value) > 100:
+            raise BrandValidationError(f"{provider}.{key} contains too many values.")
+

app/container.py

@@ -2,11 +2,48 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from app.ai.service import AiStudioService
+from app.brand.repositories.brand_repository import BrandKitRepository
+from app.brand.services.brand_service import BrandKitService
+from app.analytics.service import AnalyticsDomainService
+from app.analytics.workers.sync import AnalyticsSyncWorker
+from app.copilot.actions import CopilotActionRegistry
+from app.copilot.planner import CopilotPlanner
+from app.copilot.repository import CopilotRepository
+from app.copilot.service import CopilotService
 from app.core.config import Settings
+from app.generation.model_registry import GenerationModelRegistration, GenerationModelRegistry
+from app.generation.providers.flux import (
+    FLUX_BASE_MODEL_ID,
+    FLUX_DISTILLED_MODEL_ID,
+    FLUX_MODEL_CAPABILITY,
+    FLUX_PROVIDER_ID,
+    FLUX_TASK,
+    FluxProviderAdapter,
+)
+from app.generation.providers.registry import GenerationProviderRegistry
+from app.generation.providers.wan import WAN_MODEL_CAPABILITY, WAN_PROVIDER_ID, WanProviderAdapter
+from app.generation.repositories.generation import GenerationRepository
+from app.generation.services.generation_service import GenerationService
+from app.generation.services.output_ingestion import GenerationOutputIngestor
+from app.generation.workers.generation_worker import GenerationWorker
+from app.projects.repositories.editor_repository import ProjectEditorRepository
+from app.projects.repositories.project_repository import ProjectRepository
+from app.projects.repositories.render_repository import ProjectRenderRepository
+from app.projects.repositories.collaboration_repository import CollaborationRepository
+from app.projects.repositories.approval_repository import ApprovalRepository
+from app.projects.services.editor_service import ProjectEditorService
+from app.projects.services.project_service import ProjectService
+from app.projects.services.collaboration_service import CollaborationService
+from app.projects.services.approval_service import ApprovalService
+from app.projects.services.render_service import ProjectRenderService
+from app.projects.workers.render_worker import ProjectRenderWorker
+from app.security.assets import CanonicalAssetService
 from app.security.audit import AuditService
 from app.security.database import SecurityDatabase
 from app.security.rate_limit import APIKeyRateLimiter
 from app.security.service import APIKeyService
+from app.security.tenancy import TenantService
 from app.services.cleanup import CleanupService
 from app.services.downloader import Downloader
 from app.services.ffmpeg_service import FFmpegService
@@ -22,6 +59,7 @@ from app.social.oauth.state import OAuthStateService
 from app.social.providers.registry import build_provider_registry
 from app.social.repositories.accounts import AccountRepository
 from app.social.repositories.assets import SocialMediaAssetRepository
+from app.social.repositories.batches import PublishingBatchRepository
 from app.social.repositories.jobs import JobRepository
 from app.social.repositories.posts import PostRepository
 from app.social.repositories.tokens import TokenRepository
@@ -31,14 +69,20 @@ from app.social.services.audit_service import SocialAuditService
 from app.social.services.job_service import JobService
 from app.social.services.media_asset_service import SocialMediaAssetService
 from app.social.services.oauth_service import OAuthService
+from app.social.services.publishing_operations_service import PublishingOperationsService
 from app.social.services.publishing_service import PublishingService
 from app.social.services.scheduling_service import SchedulingService
 from app.social.services.social_service import SocialService
 from app.social.services.token_service import TokenService
 from app.templates.executor import OperationExecutor, TemplateExecutor
 from app.templates.loader import TemplateLoader
+from app.templates.marketplace_repository import MarketplaceTemplateRepository
+from app.templates.marketplace_service import MarketplaceTemplateService
 from app.templates.registry import TemplateRegistry
 from app.templates.validator import TemplateValidator
+from app.analytics.repository import AnalyticsRepository
+from app.projects.repositories.notification_repository import NotificationRepository
+from app.projects.services.notification_service import NotificationService
 
 
 @dataclass(slots=True)
@@ -55,26 +99,147 @@ class Container:
     processor: MediaProcessor
     template_registry: TemplateRegistry
     template_executor: TemplateExecutor
+    template_marketplace: MarketplaceTemplateService
     security_database: SecurityDatabase
+    tenants: TenantService
+    assets: CanonicalAssetService
     api_keys: APIKeyService
     rate_limiter: APIKeyRateLimiter
     audit: AuditService
     social: SocialService
-
+    ai: AiStudioService
+    copilot: CopilotService
+    generation: GenerationService
+    generation_models: GenerationModelRegistry
+    generation_worker: GenerationWorker
+    projects: ProjectService
+    editor: ProjectEditorService
+    renders: ProjectRenderService
+    render_worker: ProjectRenderWorker
+    analytics: AnalyticsDomainService
+    analytics_worker: AnalyticsSyncWorker
+    brand_kits: BrandKitService
+    collaboration: CollaborationService
+    approval: ApprovalService
+    notifications: NotificationService
 
 def build_container(settings: Settings) -> Container:
-    security_database = SecurityDatabase(settings.database_url)
-    api_keys = APIKeyService(security_database, settings)
+    security_database = SecurityDatabase(
+        settings.database_url, auto_migrate=settings.security_auto_migrate
+    )
+    tenants = TenantService(security_database)
+    assets = CanonicalAssetService(security_database)
+    api_keys = APIKeyService(security_database, settings, tenants)
     rate_limiter = APIKeyRateLimiter(security_database)
     audit = AuditService(security_database)
-    # Social publishing validates the same file-backed outputs as the normal
-    # media pipeline, so build those shared services before wiring Social.
+    brand_repository = BrandKitRepository(security_database)
+    brand_kits = BrandKitService(brand_repository, assets, audit)
+    projects = ProjectService(ProjectRepository(security_database), assets, audit, brand_kits)
+    collaboration = CollaborationService(CollaborationRepository(security_database))
+    approval = ApprovalService(ApprovalRepository(security_database), ProjectEditorRepository(security_database))
+    notifications = NotificationService(NotificationRepository(security_database))
     cleanup = CleanupService(settings)
+    # Generation output validation shares the established FFprobe/validator
+    # services.  Construct them before the output ingestor, without changing
+    # existing media or social provider behavior.
     validator = MediaValidator(settings)
+    ffprobe = FFprobeService(settings)
+    wan = WanProviderAdapter.from_settings(settings)
+    flux = FluxProviderAdapter.from_settings(settings)
+    generation_providers = GenerationProviderRegistry([wan, flux])
+    generation_models = GenerationModelRegistry(
+        [
+            GenerationModelRegistration(
+                provider_id=WAN_PROVIDER_ID,
+                model=WAN_MODEL_CAPABILITY,
+                configuration_reference="wan-space",
+                metadata={
+                    "underlying_model_id": "Wan-AI/Wan2.2-I2V-A14B-Diffusers",
+                    "task": "image-to-video",
+                    "fps": 16,
+                },
+            ),
+            GenerationModelRegistration(
+                provider_id=FLUX_PROVIDER_ID,
+                model=FLUX_MODEL_CAPABILITY,
+                configuration_reference="flux-space",
+                metadata={
+                    "task": FLUX_TASK,
+                    "license": "Apache-2.0",
+                    "models": {
+                        "distilled": FLUX_DISTILLED_MODEL_ID,
+                        "base": FLUX_BASE_MODEL_ID,
+                    },
+                },
+            ),
+        ]
+    )
+    generation = GenerationService(
+        settings=settings,
+        database=security_database,
+        assets=assets,
+        repository=GenerationRepository(security_database),
+        providers=generation_providers,
+        models=generation_models,
+        output_ingestor=GenerationOutputIngestor(
+            settings=settings,
+            cleanup=cleanup,
+            assets=assets,
+            ffprobe=ffprobe,
+            validator=validator,
+        ),
+    )
+    generation_worker = GenerationWorker(
+        settings=settings,
+        generation=generation,
+        assets=assets,
+        cleanup=cleanup,
+        audit=audit,
+    )
+    ai = AiStudioService(generation, projects, assets, audit)
+    # Social publishing validates the same file-backed outputs as the normal
+    # media pipeline, so build those shared services before wiring Social.
     downloader = Downloader(settings, validator)
     ytdlp = YTDLPService(settings, validator)
     ffmpeg = FFmpegService(settings)
-    ffprobe = FFprobeService(settings)
+    editor_repository = ProjectEditorRepository(security_database)
+    editor = ProjectEditorService(
+        editor_repository,
+        assets,
+        audit,
+        state_max_bytes=settings.editor_state_max_bytes,
+        max_tracks=settings.render_max_tracks,
+        max_clips=settings.render_max_clips,
+        max_duration_seconds=settings.render_max_duration_seconds,
+    )
+    render_repository = ProjectRenderRepository(security_database)
+    renders = ProjectRenderService(
+        settings, render_repository, editor_repository, assets, cleanup, audit
+    )
+    render_worker = ProjectRenderWorker(
+        settings, render_repository, renders, ffmpeg, cleanup, audit
+    )
+    template_marketplace = MarketplaceTemplateService(
+        MarketplaceTemplateRepository(security_database), assets, ai, audit
+    )
+    copilot_actions = CopilotActionRegistry(
+        projects=projects,
+        assets=assets,
+        editor=editor,
+        renders=renders,
+        ai=ai,
+        templates=template_marketplace,
+    )
+    copilot = CopilotService(
+        repository=CopilotRepository(security_database),
+        planner=CopilotPlanner(),
+        actions=copilot_actions,
+        projects=projects,
+        assets=assets,
+        editor=editor,
+        ai=ai,
+        audit=audit,
+    )
     whisper = WhisperService(settings)
     social_database = SocialDatabase(settings)
     providers = build_provider_registry(settings)
@@ -101,26 +266,66 @@ def build_container(settings: Settings) -> Container:
         social_audit,
     )
     social_media_assets = SocialMediaAssetService(
-        SocialMediaAssetRepository(social_database), cleanup, ffprobe, validator
+        settings, SocialMediaAssetRepository(social_database), assets, cleanup, ffprobe, validator
+    )
+    publishing_service = PublishingService(
+        settings,
+        post_repository,
+        job_repository,
+        account_repository,
+        providers,
+        social_media_assets,
+        oauth_service,
+        brand_kits,
+        projects,
+    )
+    scheduling_service = SchedulingService(post_repository, social_media_assets)
+    social_analytics = AnalyticsService(
+        social_database, account_repository, providers, oauth_service
     )
     social = SocialService(
         settings=settings,
         database=social_database,
         accounts=account_service,
         oauth=oauth_service,
-        publishing=PublishingService(
-            settings, post_repository, job_repository, account_repository, providers,
-            social_media_assets, oauth_service,
+        publishing=publishing_service,
+        operations=PublishingOperationsService(
+            security_database=security_database,
+            posts=post_repository,
+            jobs=job_repository,
+            accounts=account_repository,
+            batches=PublishingBatchRepository(social_database),
+            publishing=publishing_service,
+            scheduling=scheduling_service,
+            audit=social_audit,
         ),
-        scheduling=SchedulingService(post_repository, social_media_assets),
+        scheduling=scheduling_service,
         jobs=JobService(job_repository),
         media_assets=social_media_assets,
-        analytics=AnalyticsService(social_database, account_repository, providers, oauth_service),
+        analytics=social_analytics,
         audit=social_audit,
     )
+    analytics = AnalyticsDomainService(
+        AnalyticsRepository(social_database),
+        providers,
+        social_analytics,
+        account_repository,
+        social_audit,
+        projects,
+    )
+    brand_repository = BrandKitRepository(security_database)
+    brand_kits = BrandKitService(brand_repository, assets, audit)
+    analytics_worker = AnalyticsSyncWorker(
+        analytics,
+        social_database,
+        interval_seconds=settings.social_scheduler_interval_seconds,
+    )
+    copilot_actions.analytics = analytics
+    copilot_actions.publishing = social.publishing
+    copilot_actions.scheduling = social.scheduling
     resolver = InputResolver(settings, cleanup, downloader, ytdlp, validator)
     processor = MediaProcessor(
-        settings, resolver, cleanup, validator, ffmpeg, ffprobe, ytdlp, whisper
+        settings, resolver, cleanup, validator, ffmpeg, ffprobe, ytdlp, whisper, assets
     )
     operation_executor = OperationExecutor(processor)
     template_validator = TemplateValidator(operation_executor.supported_operations)
@@ -141,9 +346,27 @@ def build_container(settings: Settings) -> Container:
         processor=processor,
         template_registry=template_registry,
         template_executor=template_executor,
+        template_marketplace=template_marketplace,
         security_database=security_database,
+        tenants=tenants,
+        assets=assets,
         api_keys=api_keys,
         rate_limiter=rate_limiter,
         audit=audit,
         social=social,
+        ai=ai,
+        copilot=copilot,
+        generation=generation,
+        generation_models=generation.models,
+        generation_worker=generation_worker,
+        projects=projects,
+        editor=editor,
+        renders=renders,
+        render_worker=render_worker,
+        analytics=analytics,
+        analytics_worker=analytics_worker,
+        brand_kits=brand_kits,
+        collaboration=collaboration,
+        approval=approval,
+        notifications=notifications,
     )

app/copilot/__init__.py

@@ -0,0 +1 @@
+"""Validated orchestration over MediaRouter's existing product services."""

app/copilot/actions.py

@@ -0,0 +1,853 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import uuid4
+
+from app.ai.schemas import AiGenerateImageRequest, AiGenerateVideoRequest
+from app.ai.service import AiStudioService
+from app.analytics.schemas import AnalyticsQuery, AnalyticsSyncRequest
+from app.analytics.service import AnalyticsDomainService
+from app.copilot.errors import (
+    CopilotCapabilityError,
+    CopilotInvalidRequestError,
+    CopilotPermissionError,
+)
+from app.copilot.schemas import (
+    AiGenerateImageAction,
+    AiGenerateVideoAction,
+    AnalyticsOverviewAction,
+    AnalyticsSyncAction,
+    AssetSelectAction,
+    CopilotAction,
+    CopilotActionCapability,
+    CopilotActionResult,
+    EditorAddClipAction,
+    EditorDeleteClipAction,
+    EditorRenderAction,
+    EditorSetDurationAction,
+    EditorSplitClipAction,
+    ProjectOpenAction,
+    PublishingCancelAction,
+    PublishingCreatePostAction,
+    PublishingPublishAction,
+    PublishingScheduleAction,
+    PublishingValidateAction,
+    TemplateApplyAction,
+    TemplateCreateProjectAction,
+    TemplateGetAction,
+    TemplateSearchAction,
+)
+from app.projects.editor_schemas import (
+    AudioClip,
+    ClipTransform,
+    EditorDocument,
+    EditorSaveRequest,
+    EffectClip,
+    MediaClip,
+    ProjectRenderCreate,
+    SourceClip,
+    Track,
+)
+from app.projects.services.editor_service import ProjectEditorService
+from app.projects.services.project_service import ProjectService
+from app.projects.services.render_service import ProjectRenderService
+from app.security.assets import CanonicalAssetService
+from app.social.services.publishing_service import PublishingService
+from app.social.services.scheduling_service import SchedulingService
+from app.templates.marketplace_schemas import TemplateApply, TemplateInstantiate
+from app.templates.marketplace_service import MarketplaceTemplateService
+
+
+@dataclass(frozen=True, slots=True)
+class CopilotActionDefinition:
+    type: str
+    description: str
+    required_permission: str
+    required_capability: str
+    destructive: bool
+    external_side_effect: bool
+    requires_confirmation: bool
+    audit_event: str
+
+
+ACTION_DEFINITIONS = (
+    CopilotActionDefinition(
+        "project.open",
+        "Open a project.",
+        "projects:read",
+        "project.open",
+        False,
+        False,
+        False,
+        "copilot.project_opened",
+    ),
+    CopilotActionDefinition(
+        "asset.select",
+        "Open a canonical asset.",
+        "assets:read",
+        "asset.select",
+        False,
+        False,
+        False,
+        "copilot.asset_selected",
+    ),
+    CopilotActionDefinition(
+        "ai.generate_image",
+        "Submit image generation.",
+        "ai:generate",
+        "ai.generate_image",
+        False,
+        False,
+        True,
+        "copilot.ai_generation_requested",
+    ),
+    CopilotActionDefinition(
+        "ai.generate_video",
+        "Submit video generation.",
+        "ai:generate",
+        "ai.generate_video",
+        False,
+        False,
+        True,
+        "copilot.ai_generation_requested",
+    ),
+    CopilotActionDefinition(
+        "editor.split_clip",
+        "Split a timeline clip.",
+        "projects:update",
+        "editor.split_clip",
+        False,
+        False,
+        False,
+        "copilot.editor_updated",
+    ),
+    CopilotActionDefinition(
+        "editor.delete_clip",
+        "Delete a timeline clip.",
+        "projects:update",
+        "editor.delete_clip",
+        True,
+        False,
+        True,
+        "copilot.editor_updated",
+    ),
+    CopilotActionDefinition(
+        "editor.set_duration",
+        "Set a clip duration.",
+        "projects:update",
+        "editor.set_duration",
+        False,
+        False,
+        False,
+        "copilot.editor_updated",
+    ),
+    CopilotActionDefinition(
+        "editor.add_clip",
+        "Add an asset to the timeline.",
+        "projects:update",
+        "editor.add_clip",
+        False,
+        False,
+        False,
+        "copilot.editor_updated",
+    ),
+    CopilotActionDefinition(
+        "editor.render",
+        "Submit a project render.",
+        "projects:update",
+        "editor.render",
+        False,
+        False,
+        True,
+        "copilot.render_requested",
+    ),
+    CopilotActionDefinition(
+        "template.search",
+        "Search visible marketplace templates.",
+        "templates:read",
+        "template.search",
+        False,
+        False,
+        False,
+        "copilot.template_searched",
+    ),
+    CopilotActionDefinition(
+        "template.get",
+        "Inspect a visible marketplace template.",
+        "templates:read",
+        "template.get",
+        False,
+        False,
+        False,
+        "copilot.template_opened",
+    ),
+    CopilotActionDefinition(
+        "template.apply",
+        "Apply a template to an existing project.",
+        "templates:apply",
+        "template.apply",
+        True,
+        False,
+        True,
+        "copilot.template_applied",
+    ),
+    CopilotActionDefinition(
+        "template.create_project",
+        "Create a project from a template.",
+        "templates:apply",
+        "template.create_project",
+        False,
+        False,
+        True,
+        "copilot.template_project_created",
+    ),
+    CopilotActionDefinition(
+        "publishing.validate",
+        "Validate every social publishing target.",
+        "social:posts:write",
+        "publishing.validate",
+        False,
+        False,
+        False,
+        "copilot.publishing_validated",
+    ),
+    CopilotActionDefinition(
+        "publishing.create_post",
+        "Create a typed canonical social post draft.",
+        "social:posts:write",
+        "publishing.create_post",
+        False,
+        False,
+        False,
+        "copilot.publishing_draft_created",
+    ),
+    CopilotActionDefinition(
+        "publishing.schedule",
+        "Schedule an existing social post.",
+        "social:schedules:write",
+        "publishing.schedule",
+        False,
+        True,
+        True,
+        "copilot.publishing_scheduled",
+    ),
+    CopilotActionDefinition(
+        "publishing.publish",
+        "Publish an existing social post to its selected accounts.",
+        "social:posts:publish",
+        "publishing.publish",
+        False,
+        True,
+        True,
+        "copilot.publishing_started",
+    ),
+    CopilotActionDefinition(
+        "publishing.cancel",
+        "Cancel eligible publishing targets or request in-flight cancellation.",
+        "social:posts:write",
+        "publishing.cancel",
+        False,
+        True,
+        True,
+        "copilot.publishing_cancelled",
+    ),
+    CopilotActionDefinition(
+        "analytics.overview",
+        "Read authoritative analytics insights.",
+        "analytics:read",
+        "analytics.overview",
+        False,
+        False,
+        False,
+        "copilot.analytics_viewed",
+    ),
+    CopilotActionDefinition(
+        "analytics.sync",
+        "Queue authoritative analytics synchronization.",
+        "analytics:sync",
+        "analytics.sync",
+        False,
+        False,
+        True,
+        "copilot.analytics_sync_requested",
+    ),
+)
+
+
+class CopilotActionRegistry:
+    def __init__(
+        self,
+        *,
+        projects: ProjectService,
+        assets: CanonicalAssetService,
+        editor: ProjectEditorService,
+        renders: ProjectRenderService,
+        ai: AiStudioService,
+        templates: MarketplaceTemplateService,
+        publishing: PublishingService | None = None,
+        scheduling: SchedulingService | None = None,
+        analytics: AnalyticsDomainService | None = None,
+    ) -> None:
+        self.projects = projects
+        self.assets = assets
+        self.editor = editor
+        self.renders = renders
+        self.ai = ai
+        self.templates = templates
+        self.publishing = publishing
+        self.scheduling = scheduling
+        self.analytics = analytics
+        self.definitions = {item.type: item for item in ACTION_DEFINITIONS}
+
+    def validate(self, action: CopilotAction) -> CopilotActionDefinition:
+        definition = self.definitions.get(action.type)
+        if definition is None:
+            raise CopilotInvalidRequestError("Copilot action type is not registered.")
+        expected = {
+            "required_permission": definition.required_permission,
+            "required_capability": definition.required_capability,
+            "destructive": definition.destructive,
+            "external_side_effect": definition.external_side_effect,
+            "requires_confirmation": definition.requires_confirmation,
+        }
+        if any(getattr(action, field) != value for field, value in expected.items()):
+            raise CopilotInvalidRequestError(
+                "Copilot action policy metadata does not match the registered action."
+            )
+        return definition
+
+    def validate_plan(self, actions: list[CopilotAction]) -> None:
+        for action in actions:
+            self.validate(action)
+
+    def capabilities(self, available: set[str]) -> list[CopilotActionCapability]:
+        return [
+            CopilotActionCapability(
+                type=item.type,
+                description=item.description,
+                required_permission=item.required_permission,
+                required_capability=item.required_capability,
+                destructive=item.destructive,
+                external_side_effect=item.external_side_effect,
+                requires_confirmation=item.requires_confirmation,
+                available=item.required_capability in available,
+            )
+            for item in ACTION_DEFINITIONS
+        ]
+
+    async def execute(
+        self,
+        action: CopilotAction,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        run_id: str,
+        permissions: frozenset[str],
+        available_capabilities: set[str],
+    ) -> CopilotActionResult:
+        definition = self.validate(action)
+        if definition.required_permission not in permissions and "admin" not in permissions:
+            raise CopilotPermissionError(
+                f"Permission '{definition.required_permission}' is required."
+            )
+        if definition.required_capability not in available_capabilities:
+            raise CopilotCapabilityError(
+                f"Capability '{definition.required_capability}' is unavailable."
+            )
+        if isinstance(action, EditorRenderAction) and not (
+            "jobs:create" in permissions or "admin" in permissions
+        ):
+            raise CopilotPermissionError("Permission 'jobs:create' is required.")
+        if isinstance(action, TemplateApplyAction) and not (
+            "projects:update" in permissions or "admin" in permissions
+        ):
+            raise CopilotPermissionError("Permission 'projects:update' is required.")
+        if isinstance(action, TemplateCreateProjectAction) and not (
+            "projects:create" in permissions or "admin" in permissions
+        ):
+            raise CopilotPermissionError("Permission 'projects:create' is required.")
+        if (
+            isinstance(action, (TemplateApplyAction, TemplateCreateProjectAction))
+            and any(
+                binding.asset_id is not None for binding in action.arguments.slot_bindings.values()
+            )
+            and not ("assets:read" in permissions or "admin" in permissions)
+        ):
+            raise CopilotPermissionError("Permission 'assets:read' is required.")
+        if isinstance(
+            action,
+            (AiGenerateVideoAction, EditorAddClipAction),
+        ) and not ("assets:read" in permissions or "admin" in permissions):
+            raise CopilotPermissionError("Permission 'assets:read' is required.")
+        if (
+            isinstance(action, AiGenerateImageAction)
+            and action.arguments.source_asset_id is not None
+            and not ("assets:read" in permissions or "admin" in permissions)
+        ):
+            raise CopilotPermissionError("Permission 'assets:read' is required.")
+        if isinstance(action, ProjectOpenAction):
+            project = await self.projects.get(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                project_id=str(action.arguments.project_id),
+            )
+            return self._success(action, "Project is ready to open.", "project", project.id)
+        if isinstance(action, AssetSelectAction):
+            asset = await self.assets.get_owned_by_id(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                asset_id=str(action.arguments.asset_id),
+            )
+            if action.arguments.project_id is not None and asset.project_id != str(
+                action.arguments.project_id
+            ):
+                raise CopilotInvalidRequestError(
+                    "The selected asset does not belong to the selected project."
+                )
+            return self._success(action, "Asset is ready to open.", "asset", asset.id)
+        if isinstance(
+            action,
+            (
+                PublishingValidateAction,
+                PublishingCreatePostAction,
+                PublishingScheduleAction,
+                PublishingPublishAction,
+                PublishingCancelAction,
+            ),
+        ):
+            if self.publishing is None or self.scheduling is None:
+                raise CopilotCapabilityError("Publishing orchestration is unavailable.")
+            if isinstance(action, PublishingValidateAction):
+                result = await self.publishing.validate_post_targets(
+                    workspace_id, str(action.arguments.post_id)
+                )
+                return self._success(
+                    action,
+                    (
+                        "Publishing targets are valid."
+                        if result.valid
+                        else "Publishing validation found issues."
+                    ),
+                    "social_post",
+                    result.post_id,
+                )
+            if isinstance(action, PublishingCreatePostAction):
+                result = await self.publishing.create(
+                    workspace_id=workspace_id,
+                    user_id=user_id,
+                    payload=action.arguments.post,
+                    idempotency_key=f"copilot:{run_id}:{action.id}",
+                )
+                return self._success(
+                    action, "Publishing draft was created.", "social_post", result.id
+                )
+            if isinstance(action, PublishingScheduleAction):
+                validation = await self.publishing.validate_post_targets(
+                    workspace_id, str(action.arguments.post_id)
+                )
+                if not validation.valid:
+                    raise CopilotInvalidRequestError(
+                        "Publishing validation must pass before scheduling."
+                    )
+                result = await self.scheduling.schedule(
+                    workspace_id, str(action.arguments.post_id), action.arguments.schedule
+                )
+                return self._success(
+                    action, "Publishing was scheduled.", "social_schedule", result.id
+                )
+            if isinstance(action, PublishingPublishAction):
+                jobs = await self.publishing.queue(
+                    workspace_id,
+                    str(action.arguments.post_id),
+                    idempotency_key=f"copilot:{run_id}:{action.id}",
+                )
+                return self._success(
+                    action,
+                    f"Queued {len(jobs)} publishing targets.",
+                    "social_post",
+                    str(action.arguments.post_id),
+                )
+            result = await self.publishing.cancel(workspace_id, str(action.arguments.post_id))
+            return self._success(
+                action,
+                "Cancellation was applied to eligible publishing targets.",
+                "social_post",
+                result.id,
+            )
+        if isinstance(action, (AnalyticsOverviewAction, AnalyticsSyncAction)):
+            if self.analytics is None:
+                raise CopilotCapabilityError("Analytics orchestration is unavailable.")
+            if isinstance(action, AnalyticsOverviewAction):
+                result = await self.analytics.overview(
+                    workspace_id,
+                    AnalyticsQuery(
+                        project_id=(
+                            str(action.arguments.project_id)
+                            if action.arguments.project_id
+                            else None
+                        ),
+                        provider=action.arguments.provider,
+                        metric=action.arguments.metric,
+                        timezone=action.arguments.timezone,
+                        sort=action.arguments.metric,
+                    ),
+                )
+                freshness = result.freshness.status
+                return self._success(
+                    action,
+                    f"Analytics overview is {freshness}; unavailable metrics were not inferred.",
+                    "analytics_overview",
+                    (
+                        str(action.arguments.project_id)
+                        if action.arguments.project_id
+                        else workspace_id
+                    ),
+                )
+            result = await self.analytics.create_sync(
+                workspace_id,
+                user_id,
+                AnalyticsSyncRequest(
+                    project_id=(
+                        str(action.arguments.project_id) if action.arguments.project_id else None
+                    ),
+                    provider=action.arguments.provider,
+                    timezone=action.arguments.timezone,
+                    idempotency_key=f"copilot:{run_id}:{action.id}",
+                ),
+            )
+            return self._success(
+                action, "Analytics synchronization was queued.", "analytics_sync", result.id
+            )
+        if isinstance(action, TemplateSearchAction):
+            result = await self.templates.list(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                search=action.arguments.query,
+                category=action.arguments.category,
+                aspect_ratio=None,
+                min_duration_ms=None,
+                max_duration_ms=None,
+                media_type=None,
+                visibility=None,
+                status=None,
+                capability=None,
+                available_only=False,
+                offset=0,
+                limit=24,
+            )
+            return self._success(
+                action,
+                f"Found {result.total} visible templates.",
+                "template_search",
+                action.arguments.query,
+            )
+        if isinstance(action, TemplateGetAction):
+            template = await self.templates.get(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                template_id=str(action.arguments.template_id),
+            )
+            return self._success(action, "Template is ready to open.", "template", template.id)
+        if isinstance(action, TemplateApplyAction):
+            result = await self.templates.apply(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                api_key_id=api_key_id,
+                request_id=request_id,
+                template_id=str(action.arguments.template_id),
+                payload=TemplateApply(
+                    project_id=action.arguments.project_id,
+                    template_version_id=action.arguments.template_version_id,
+                    slot_bindings=action.arguments.slot_bindings,
+                ),
+                idempotency_key=f"copilot:{run_id}:{action.id}",
+                instantiate=False,
+            )
+            return self._success(
+                action, "Template was applied to the project.", "project", result.project_id
+            )
+        if isinstance(action, TemplateCreateProjectAction):
+            result = await self.templates.apply(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                api_key_id=api_key_id,
+                request_id=request_id,
+                template_id=str(action.arguments.template_id),
+                payload=TemplateInstantiate(
+                    project_name=action.arguments.project_name,
+                    template_version_id=action.arguments.template_version_id,
+                    slot_bindings=action.arguments.slot_bindings,
+                ),
+                idempotency_key=f"copilot:{run_id}:{action.id}",
+                instantiate=True,
+            )
+            return self._success(
+                action, "Project was created from the template.", "project", result.project_id
+            )
+        if isinstance(action, AiGenerateImageAction):
+            job = await self.ai.create(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                api_key_id=api_key_id,
+                request_id=request_id,
+                idempotency_key=f"copilot:{run_id}:{action.id}",
+                payload=AiGenerateImageRequest(
+                    operation="generate_image",
+                    prompt=action.arguments.prompt,
+                    model=action.arguments.model,
+                    project_id=action.arguments.project_id,
+                    source_asset_ids=(
+                        [action.arguments.source_asset_id]
+                        if action.arguments.source_asset_id
+                        else []
+                    ),
+                ),
+            )
+            return self._success(
+                action, "Image generation was submitted.", "ai_generation", job.generation_id
+            )
+        if isinstance(action, AiGenerateVideoAction):
+            job = await self.ai.create(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                api_key_id=api_key_id,
+                request_id=request_id,
+                idempotency_key=f"copilot:{run_id}:{action.id}",
+                payload=AiGenerateVideoRequest(
+                    operation="generate_video",
+                    prompt=action.arguments.prompt,
+                    model=action.arguments.model,
+                    project_id=action.arguments.project_id,
+                    source_asset_ids=[action.arguments.source_asset_id],
+                ),
+            )
+            return self._success(
+                action, "Video generation was submitted.", "ai_generation", job.generation_id
+            )
+        if isinstance(action, EditorRenderAction):
+            render = await self.renders.create(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                api_key_id=api_key_id,
+                request_id=request_id,
+                project_id=str(action.arguments.project_id),
+                idempotency_key=f"copilot:{run_id}:{action.id}",
+                payload=ProjectRenderCreate(editor_revision=action.arguments.expected_revision),
+            )
+            return self._success(action, "Render was submitted.", "project_render", render.id)
+        if isinstance(
+            action,
+            (
+                EditorSplitClipAction,
+                EditorDeleteClipAction,
+                EditorSetDurationAction,
+                EditorAddClipAction,
+            ),
+        ):
+            revision = await self._execute_editor_action(
+                action,
+                workspace_id=workspace_id,
+                user_id=user_id,
+                api_key_id=api_key_id,
+                request_id=request_id,
+            )
+            return self._success(
+                action,
+                f"Editor revision {revision} was saved.",
+                "project_editor_revision",
+                str(revision),
+            )
+        raise CopilotInvalidRequestError("Copilot action type is not registered.")
+
+    async def _execute_editor_action(
+        self,
+        action,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+    ) -> int:
+        project_id = str(action.arguments.project_id)
+        current = await self.editor.get(
+            workspace_id=workspace_id, user_id=user_id, project_id=project_id
+        )
+        if current.revision != action.arguments.expected_revision:
+            raise CopilotInvalidRequestError(
+                "The editor changed after this plan was created. Create a new plan."
+            )
+        document = current.state.model_copy(deep=True)
+        if isinstance(action, EditorSplitClipAction):
+            self._split(document, action.arguments.clip_id, action.arguments.at_ms)
+        elif isinstance(action, EditorDeleteClipAction):
+            self._delete(document, action.arguments.clip_id)
+        elif isinstance(action, EditorSetDurationAction):
+            self._set_duration(document, action.arguments.clip_id, action.arguments.duration_ms)
+        elif isinstance(action, EditorAddClipAction):
+            await self._add_clip(
+                document,
+                workspace_id=workspace_id,
+                user_id=user_id,
+                project_id=project_id,
+                asset_id=str(action.arguments.asset_id),
+                duration_ms=action.arguments.duration_ms,
+            )
+        validated = EditorDocument.model_validate(document.model_dump(by_alias=True))
+        saved = await self.editor.save(
+            workspace_id=workspace_id,
+            user_id=user_id,
+            api_key_id=api_key_id,
+            request_id=request_id,
+            project_id=project_id,
+            payload=EditorSaveRequest(
+                expected_revision=current.revision,
+                schema_version=validated.schema_version,
+                state=validated,
+            ),
+        )
+        return saved.revision
+
+    @staticmethod
+    def _find_clip(document: EditorDocument, clip_id: str):
+        for track in document.timeline.tracks:
+            for index, clip in enumerate(track.clips):
+                if clip.id == clip_id:
+                    return track, index, clip
+        raise CopilotInvalidRequestError("The selected clip no longer exists.")
+
+    def _split(self, document: EditorDocument, clip_id: str, at_ms: int) -> None:
+        track, index, clip = self._find_clip(document, clip_id)
+        relative = at_ms - clip.start_ms
+        if relative <= 0 or relative >= clip.duration_ms:
+            raise CopilotInvalidRequestError("The split point must fall inside the selected clip.")
+        right = clip.model_copy(deep=True)
+        right.id = str(uuid4())
+        right.start_ms = at_ms
+        right.duration_ms = clip.duration_ms - relative
+        clip.duration_ms = relative
+        if isinstance(clip, SourceClip) and isinstance(right, SourceClip):
+            right.source_start_ms = clip.source_start_ms + relative
+            right.source_duration_ms = right.duration_ms
+            clip.source_duration_ms = clip.duration_ms
+        track.clips.insert(index + 1, right)
+
+    def _delete(self, document: EditorDocument, clip_id: str) -> None:
+        track, index, _ = self._find_clip(document, clip_id)
+        track.clips.pop(index)
+        document.timeline.transitions = [
+            item
+            for item in document.timeline.transitions
+            if item.from_clip_id != clip_id and item.to_clip_id != clip_id
+        ]
+        for candidate in document.timeline.tracks:
+            candidate.clips = [
+                clip
+                for clip in candidate.clips
+                if not (isinstance(clip, EffectClip) and clip.target_clip_id == clip_id)
+            ]
+
+    def _set_duration(self, document: EditorDocument, clip_id: str, duration_ms: int) -> None:
+        _, _, clip = self._find_clip(document, clip_id)
+        if isinstance(clip, SourceClip) and not (
+            isinstance(clip, MediaClip) and clip.media_type == "image"
+        ):
+            raise CopilotInvalidRequestError(
+                "Only image or non-source clips can be extended without media analysis."
+            )
+        clip.duration_ms = duration_ms
+        if isinstance(clip, SourceClip):
+            clip.source_duration_ms = duration_ms
+
+    async def _add_clip(
+        self,
+        document: EditorDocument,
+        *,
+        workspace_id: str,
+        user_id: str,
+        project_id: str,
+        asset_id: str,
+        duration_ms: int,
+    ) -> None:
+        asset = await self.assets.get_owned_by_id(
+            workspace_id=workspace_id, user_id=user_id, asset_id=asset_id
+        )
+        if asset.project_id != project_id:
+            raise CopilotInvalidRequestError("The selected asset is not attached to this project.")
+        mime = asset.mime_type
+        if mime.startswith("audio/"):
+            track_type = "audio"
+            kind = "audio"
+        elif mime.startswith("video/"):
+            track_type = "video"
+            kind = "video"
+        elif mime.startswith("image/"):
+            track_type = "video"
+            kind = "image"
+        else:
+            raise CopilotInvalidRequestError("This asset type cannot be added to the timeline.")
+        track = next(
+            (item for item in document.timeline.tracks if item.type == track_type),
+            None,
+        )
+        if track is None:
+            track = Track(
+                id=str(uuid4()),
+                type=track_type,
+                name="Copilot media",
+                order=len(document.timeline.tracks),
+                muted=False,
+                locked=False,
+                visible=True,
+                clips=[],
+            )
+            document.timeline.tracks.append(track)
+        metadata = asset.metadata_json or {}
+        source_duration = metadata.get("duration_ms")
+        if source_duration is None and isinstance(metadata.get("duration"), (int, float)):
+            source_duration = round(float(metadata["duration"]) * 1_000)
+        clip_duration = duration_ms if kind == "image" else source_duration
+        if not isinstance(clip_duration, int) or clip_duration <= 0:
+            raise CopilotInvalidRequestError("The asset has no validated duration metadata.")
+        common = {
+            "id": str(uuid4()),
+            "trackId": track.id,
+            "label": asset.filename[:500],
+            "startMs": document.duration_ms(),
+            "durationMs": clip_duration,
+            "visible": True,
+            "opacity": 1,
+            "metadata": {},
+            "assetId": asset.id,
+            "sourceStartMs": 0,
+            "sourceDurationMs": clip_duration,
+        }
+        if kind == "audio":
+            track.clips.append(AudioClip(**common, kind="audio", volume=1, fadeInMs=0, fadeOutMs=0))
+        else:
+            track.clips.append(
+                MediaClip(
+                    **common,
+                    kind="media",
+                    mediaType=kind,
+                    transform=ClipTransform(x=0, y=0, scaleX=1, scaleY=1, rotation=0),
+                    volume=1,
+                )
+            )
+
+    @staticmethod
+    def _success(
+        action: CopilotAction,
+        summary: str,
+        resource_type: str,
+        resource_id: str,
+    ) -> CopilotActionResult:
+        return CopilotActionResult(
+            action_id=action.id,
+            action_type=action.type,
+            status="completed",
+            summary=summary,
+            resource_type=resource_type,
+            resource_id=resource_id,
+        )

app/copilot/api.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Header, Path, Query, Request, status
+
+from app.copilot.schemas import (
+    CopilotCapabilities,
+    CopilotContextInput,
+    CopilotExecuteRequest,
+    CopilotRun,
+    CopilotRunCreate,
+    CopilotRunList,
+)
+from app.security.errors import ForbiddenError
+
+router = APIRouter(prefix="/v1/copilot", tags=["copilot"])
+
+
+def _identity(request: Request):
+    context = request.state.auth
+    if not context.workspace_id or not context.user_id:
+        raise ForbiddenError
+    return context
+
+
+@router.post("/capabilities", response_model=CopilotCapabilities)
+async def capabilities(request: Request, context: CopilotContextInput) -> CopilotCapabilities:
+    identity = _identity(request)
+    return await request.app.state.container.copilot.capabilities(
+        workspace_id=identity.workspace_id,
+        user_id=identity.user_id,
+        context=context,
+    )
+
+
+@router.post("/runs", response_model=CopilotRun, status_code=status.HTTP_201_CREATED)
+async def create_run(
+    request: Request,
+    payload: CopilotRunCreate,
+    idempotency_key: Annotated[str, Header(alias="Idempotency-Key", min_length=8, max_length=255)],
+) -> CopilotRun:
+    identity = _identity(request)
+    return await request.app.state.container.copilot.create_run(
+        workspace_id=identity.workspace_id,
+        user_id=identity.user_id,
+        api_key_id=identity.api_key_id,
+        request_id=request.state.request_id,
+        payload=payload,
+        idempotency_key=idempotency_key,
+    )
+
+
+@router.get("/runs", response_model=CopilotRunList)
+async def list_runs(
+    request: Request,
+    offset: Annotated[int, Query(ge=0)] = 0,
+    limit: Annotated[int, Query(ge=1, le=100)] = 25,
+) -> CopilotRunList:
+    identity = _identity(request)
+    return await request.app.state.container.copilot.list(
+        workspace_id=identity.workspace_id,
+        user_id=identity.user_id,
+        offset=offset,
+        limit=limit,
+    )
+
+
+@router.get("/history", response_model=CopilotRunList)
+async def history(
+    request: Request,
+    offset: Annotated[int, Query(ge=0)] = 0,
+    limit: Annotated[int, Query(ge=1, le=100)] = 25,
+) -> CopilotRunList:
+    return await list_runs(request, offset, limit)
+
+
+@router.get("/runs/{run_id}", response_model=CopilotRun)
+async def get_run(
+    request: Request,
+    run_id: Annotated[str, Path(min_length=36, max_length=36)],
+) -> CopilotRun:
+    identity = _identity(request)
+    return await request.app.state.container.copilot.get(
+        workspace_id=identity.workspace_id,
+        user_id=identity.user_id,
+        run_id=run_id,
+    )
+
+
+@router.post("/runs/{run_id}/execute", response_model=CopilotRun)
+async def execute_run(
+    request: Request,
+    payload: CopilotExecuteRequest,
+    run_id: Annotated[str, Path(min_length=36, max_length=36)],
+) -> CopilotRun:
+    identity = _identity(request)
+    return await request.app.state.container.copilot.execute(
+        workspace_id=identity.workspace_id,
+        user_id=identity.user_id,
+        api_key_id=identity.api_key_id,
+        request_id=request.state.request_id,
+        run_id=run_id,
+        payload=payload,
+        permissions=identity.scopes,
+    )
+
+
+@router.post("/runs/{run_id}/cancel", response_model=CopilotRun)
+async def cancel_run(
+    request: Request,
+    run_id: Annotated[str, Path(min_length=36, max_length=36)],
+) -> CopilotRun:
+    identity = _identity(request)
+    return await request.app.state.container.copilot.cancel(
+        workspace_id=identity.workspace_id,
+        user_id=identity.user_id,
+        api_key_id=identity.api_key_id,
+        request_id=request.state.request_id,
+        run_id=run_id,
+    )

app/copilot/errors.py

@@ -0,0 +1,36 @@
+from app.core.exceptions import MediaAPIError
+
+
+class CopilotInvalidRequestError(MediaAPIError):
+    code = "COPILOT_INVALID_REQUEST"
+    status_code = 422
+
+
+class CopilotUnsupportedIntentError(MediaAPIError):
+    code = "COPILOT_UNSUPPORTED_INTENT"
+    status_code = 422
+
+
+class CopilotRunNotFoundError(MediaAPIError):
+    code = "COPILOT_RUN_NOT_FOUND"
+    status_code = 404
+
+
+class CopilotRunConflictError(MediaAPIError):
+    code = "COPILOT_RUN_CONFLICT"
+    status_code = 409
+
+
+class CopilotConfirmationRequiredError(MediaAPIError):
+    code = "COPILOT_CONFIRMATION_REQUIRED"
+    status_code = 409
+
+
+class CopilotPermissionError(MediaAPIError):
+    code = "COPILOT_ACTION_FORBIDDEN"
+    status_code = 403
+
+
+class CopilotCapabilityError(MediaAPIError):
+    code = "COPILOT_CAPABILITY_UNAVAILABLE"
+    status_code = 422

app/copilot/models.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import uuid4
+
+from sqlalchemy import (
+    JSON,
+    CheckConstraint,
+    DateTime,
+    ForeignKey,
+    Index,
+    String,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.security.models import Base, utcnow
+
+
+class CopilotRunRecord(Base):
+    __tablename__ = "copilot_runs"
+    __table_args__ = (
+        UniqueConstraint(
+            "workspace_id", "idempotency_key", name="uq_copilot_run_workspace_idempotency"
+        ),
+        CheckConstraint(
+            "status in ('plan_ready','blocked','executing','completed','partial','failed','cancelled')",
+            name="ck_copilot_run_status",
+        ),
+        Index("ix_copilot_runs_workspace_created", "workspace_id", "created_at"),
+        Index("ix_copilot_runs_workspace_status", "workspace_id", "status"),
+        Index("ix_copilot_runs_project_created", "project_id", "created_at"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    workspace_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("workspaces.id", ondelete="RESTRICT"), nullable=False
+    )
+    user_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("users.id", ondelete="RESTRICT"), nullable=False
+    )
+    project_id: Mapped[str | None] = mapped_column(
+        String(36), ForeignKey("projects.id", ondelete="RESTRICT")
+    )
+    idempotency_key: Mapped[str] = mapped_column(String(255), nullable=False)
+    request_fingerprint: Mapped[str] = mapped_column(String(64), nullable=False)
+    request_text: Mapped[str] = mapped_column(Text, nullable=False)
+    context_json: Mapped[dict[str, object]] = mapped_column("context", JSON, nullable=False)
+    plan_json: Mapped[dict[str, object]] = mapped_column("plan", JSON, nullable=False)
+    status: Mapped[str] = mapped_column(String(32), nullable=False)
+    current_action_id: Mapped[str | None] = mapped_column(String(64))
+    results_json: Mapped[list[dict[str, object]]] = mapped_column(
+        "results", JSON, nullable=False, default=list
+    )
+    summary: Mapped[str | None] = mapped_column(Text)
+    error_code: Mapped[str | None] = mapped_column(String(100))
+    error_message: Mapped[str | None] = mapped_column(Text)
+    confirmed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=utcnow
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow
+    )
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))

app/copilot/planner.py

@@ -0,0 +1,627 @@
+from __future__ import annotations
+
+import re
+from uuid import uuid4
+
+from app.copilot.schemas import (
+    AiGenerateImageAction,
+    AiGenerateImageArguments,
+    AiGenerateVideoAction,
+    AiGenerateVideoArguments,
+    AnalyticsOverviewAction,
+    AnalyticsOverviewArguments,
+    AnalyticsSyncAction,
+    AnalyticsSyncArguments,
+    AssetSelectAction,
+    AssetSelectArguments,
+    ShareProjectAction,
+    ShareProjectArguments,
+    CopilotContext,
+    CopilotPlan,
+    EditorAddClipAction,
+    EditorAddClipArguments,
+    EditorDeleteClipAction,
+    EditorDeleteClipArguments,
+    EditorRenderAction,
+    EditorRenderArguments,
+    EditorSetDurationAction,
+    EditorSetDurationArguments,
+    EditorSplitClipAction,
+    EditorSplitClipArguments,
+    ProjectOpenAction,
+    ProjectOpenArguments,
+    PublishingCancelAction,
+    PublishingCancelArguments,
+    PublishingPublishAction,
+    PublishingPublishArguments,
+    PublishingValidateAction,
+    PublishingValidateArguments,
+    TemplateApplyAction,
+    TemplateApplyArguments,
+    TemplateCreateProjectAction,
+    TemplateCreateProjectArguments,
+    TemplateGetAction,
+    TemplateGetArguments,
+    TemplateSearchAction,
+    TemplateSearchArguments,
+)
+
+
+class CopilotPlanner:
+    """Closed deterministic planner used until a text tool-calling model exists."""
+
+    def plan(self, request: str, context: CopilotContext) -> CopilotPlan:
+        normalized = " ".join(request.strip().split())
+        lowered = normalized.casefold()
+        action_id = str(uuid4())
+        project_id = context.project_id
+        selected_asset = context.selected_asset_ids[0] if context.selected_asset_ids else None
+        selected_clip = context.selected_clip_ids[0] if context.selected_clip_ids else None
+        revision = context.editor_summary.revision if context.editor_summary else None
+
+        unavailable = (
+            None
+            if "template" in lowered
+            else self._requested_unavailable_capability(lowered, context)
+        )
+        if unavailable:
+            return self._blocked(
+                normalized,
+                f"This request requires {unavailable}, but that capability is not available.",
+                unsupported=[unavailable],
+            )
+
+        template_id = self._template_id(lowered)
+        publishing_post_id = self._template_id(lowered)
+        if "analytics" in lowered and re.search(r"\b(sync|refresh|update)\b", lowered):
+            action = AnalyticsSyncAction(
+                id=action_id,
+                type="analytics.sync",
+                arguments=AnalyticsSyncArguments(project_id=project_id),
+                reason="Queue a durable synchronization through authorized provider adapters.",
+                requires_confirmation=True,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="analytics:sync",
+                required_capability="analytics.sync",
+            )
+            return self._plan(
+                "Sync analytics",
+                "Queue an idempotent authoritative analytics synchronization.",
+                [action],
+            )
+        if re.search(r"\b(analytics|performance|performing|insights)\b", lowered):
+            metric = next(
+                (
+                    item
+                    for item in (
+                        "views",
+                        "impressions",
+                        "likes",
+                        "comments",
+                        "shares",
+                        "engagement_rate",
+                    )
+                    if item.replace("_", " ") in lowered
+                ),
+                "views",
+            )
+            action = AnalyticsOverviewAction(
+                id=action_id,
+                type="analytics.overview",
+                arguments=AnalyticsOverviewArguments(project_id=project_id, metric=metric),
+                reason="Read synchronized provider metrics without inferring unavailable values.",
+                requires_confirmation=False,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="analytics:read",
+                required_capability="analytics.overview",
+            )
+            return self._plan(
+                "Review analytics",
+                "Read authoritative analytics and report freshness explicitly.",
+                [action],
+            )
+        if publishing_post_id and re.search(r"\b(validate|check)\b.*\b(publish|post)\b", lowered):
+            action = PublishingValidateAction(
+                id=action_id,
+                type="publishing.validate",
+                arguments=PublishingValidateArguments(post_id=publishing_post_id),
+                reason="Validate the existing canonical post and every selected provider target.",
+                requires_confirmation=False,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="social:posts:write",
+                required_capability="publishing.validate",
+            )
+            return self._plan(
+                "Validate publishing",
+                "Run authoritative per-target publishing validation.",
+                [action],
+            )
+        if publishing_post_id and re.search(r"\b(publish|send)\b", lowered):
+            action = PublishingPublishAction(
+                id=action_id,
+                type="publishing.publish",
+                arguments=PublishingPublishArguments(post_id=publishing_post_id),
+                reason="Publish the explicitly identified canonical post to its already selected accounts.",
+                requires_confirmation=True,
+                destructive=False,
+                external_side_effect=True,
+                required_permission="social:posts:publish",
+                required_capability="publishing.publish",
+            )
+            return self._plan(
+                "Publish social post",
+                "Validate and queue external publishing only after explicit confirmation.",
+                [action],
+            )
+        if publishing_post_id and re.search(r"\bcancel\b.*\b(publish|post)\b", lowered):
+            action = PublishingCancelAction(
+                id=action_id,
+                type="publishing.cancel",
+                arguments=PublishingCancelArguments(post_id=publishing_post_id),
+                reason="Cancel eligible jobs and request cancellation for in-flight provider work.",
+                requires_confirmation=True,
+                destructive=False,
+                external_side_effect=True,
+                required_permission="social:posts:write",
+                required_capability="publishing.cancel",
+            )
+            return self._plan(
+                "Cancel publishing",
+                "Apply truthful cancellation semantics after confirmation.",
+                [action],
+            )
+        if "template" in lowered and re.search(r"\b(find|search|browse)\b", lowered):
+            query = re.sub(
+                r"(?i)\b(find|search|browse|for|me|a|an|template|templates)\b", " ", normalized
+            )
+            query = " ".join(query.split()) or normalized
+            category = next(
+                (
+                    item
+                    for item in (
+                        "business",
+                        "marketing",
+                        "education",
+                        "podcast",
+                        "gaming",
+                        "news",
+                        "social",
+                        "youtube",
+                        "tiktok",
+                        "instagram",
+                        "product",
+                        "personal",
+                    )
+                    if item in lowered
+                ),
+                None,
+            )
+            action = TemplateSearchAction(
+                id=action_id,
+                type="template.search",
+                arguments=TemplateSearchArguments(query=query, category=category),
+                reason="Search the authoritative visible template catalog.",
+                requires_confirmation=False,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="templates:read",
+                required_capability="template.search",
+            )
+            return self._plan(
+                "Search templates",
+                "Search the versioned marketplace catalog using the current workspace context.",
+                [action],
+            )
+
+        if "share" in lowered and "project" in lowered and re.search(r"\b(with)\b", lowered):
+            # Example parsing for demo purposes
+            project_id = "..." # simplified
+            user_id = "..." # simplified
+            role = "viewer"
+            action = ShareProjectAction(
+                id=action_id,
+                type="project.share",
+                arguments=ShareProjectArguments(project_id=project_id, user_id=user_id, role=role),
+                reason="Share project with user.",
+                requires_confirmation=True,
+                destructive=False,
+                external_side_effect=True,
+                required_permission="projects:share",
+                required_capability="project.share",
+            )
+            return self._plan("Share project", "Share project with another user.", [action])
+
+        if template_id and "template" in lowered and re.search(r"\b(open|show|inspect)\b", lowered):
+            action = TemplateGetAction(
+                id=action_id,
+                type="template.get",
+                arguments=TemplateGetArguments(template_id=template_id),
+                reason="Inspect the selected authoritative template.",
+                requires_confirmation=False,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="templates:read",
+                required_capability="template.get",
+            )
+            return self._plan("Open template", "Open the selected template.", [action])
+
+        if template_id and "template" in lowered and re.search(r"\b(use|apply)\b", lowered):
+            if project_id is None:
+                return self._blocked(
+                    normalized,
+                    "Applying a template requires a selected project.",
+                    missing=["project"],
+                )
+            action = TemplateApplyAction(
+                id=action_id,
+                type="template.apply",
+                arguments=TemplateApplyArguments(
+                    template_id=template_id,
+                    project_id=project_id,
+                    slot_bindings={},
+                ),
+                reason="Apply the selected versioned template to the current project.",
+                requires_confirmation=True,
+                destructive=True,
+                external_side_effect=False,
+                required_permission="templates:apply",
+                required_capability="template.apply",
+            )
+            return self._plan(
+                "Apply template",
+                "Validate requirements and replace the current authoritative editor state after confirmation.",
+                [action],
+            )
+
+        if template_id and "template" in lowered and "create project" in lowered:
+            name_match = re.search(r'\bnamed\s+["“]?([^"”]+?)["”]?\s*$', normalized, re.IGNORECASE)
+            if name_match is None:
+                return self._blocked(
+                    normalized,
+                    "Creating a project from a template requires an explicit project name.",
+                    missing=["project name"],
+                )
+            action = TemplateCreateProjectAction(
+                id=action_id,
+                type="template.create_project",
+                arguments=TemplateCreateProjectArguments(
+                    template_id=template_id,
+                    project_name=name_match.group(1).strip(),
+                    slot_bindings={},
+                ),
+                reason="Create an editable project from the selected template.",
+                requires_confirmation=True,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="templates:apply",
+                required_capability="template.create_project",
+            )
+            return self._plan(
+                "Create project from template",
+                "Validate requirements and create a new editable project after confirmation.",
+                [action],
+            )
+
+        if re.search(r"\b(open|show)\b.*\bproject\b", lowered):
+            if project_id is None:
+                return self._blocked(normalized, "Select a project first.", missing=["project"])
+            action = ProjectOpenAction(
+                id=action_id,
+                type="project.open",
+                arguments=ProjectOpenArguments(project_id=project_id),
+                reason="Open the selected project.",
+                requires_confirmation=False,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="projects:read",
+                required_capability="project.open",
+            )
+            return self._plan("Open project", "Open the selected project.", [action])
+
+        if re.search(r"\b(open|select|show)\b.*\basset\b", lowered):
+            if selected_asset is None:
+                return self._blocked(normalized, "Select an asset first.", missing=["asset"])
+            action = AssetSelectAction(
+                id=action_id,
+                type="asset.select",
+                arguments=AssetSelectArguments(asset_id=selected_asset, project_id=project_id),
+                reason="Open the selected canonical asset.",
+                requires_confirmation=False,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="assets:read",
+                required_capability="asset.select",
+            )
+            return self._plan("Open asset", "Open the selected asset.", [action])
+
+        if "generate" in lowered and ("video" in lowered or "animate" in lowered):
+            if "ai.generate_video" not in context.available_capabilities:
+                return self._blocked(
+                    normalized,
+                    "Video generation is not currently available.",
+                    unsupported=["ai.generate_video"],
+                )
+            if selected_asset is None:
+                return self._blocked(
+                    normalized,
+                    "Video generation requires a selected source image.",
+                    missing=["source image asset"],
+                )
+            prompt = self._generation_prompt(normalized, "video")
+            action = AiGenerateVideoAction(
+                id=action_id,
+                type="ai.generate_video",
+                arguments=AiGenerateVideoArguments(
+                    prompt=prompt,
+                    project_id=project_id,
+                    source_asset_id=selected_asset,
+                ),
+                reason="Submit a real image-to-video generation job.",
+                requires_confirmation=True,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="ai:generate",
+                required_capability="ai.generate_video",
+            )
+            return self._plan(
+                "Generate video",
+                "Generate a video from the selected image using AI Studio.",
+                [action],
+            )
+
+        if "generate" in lowered and any(
+            word in lowered for word in ("image", "thumbnail", "artwork")
+        ):
+            if "ai.generate_image" not in context.available_capabilities:
+                return self._blocked(
+                    normalized,
+                    "Image generation is not currently available.",
+                    unsupported=["ai.generate_image"],
+                )
+            prompt = self._generation_prompt(normalized, "image")
+            action = AiGenerateImageAction(
+                id=action_id,
+                type="ai.generate_image",
+                arguments=AiGenerateImageArguments(
+                    prompt=prompt,
+                    project_id=project_id,
+                    source_asset_id=selected_asset,
+                ),
+                reason="Submit a real image generation job.",
+                requires_confirmation=True,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="ai:generate",
+                required_capability="ai.generate_image",
+            )
+            return self._plan(
+                "Generate image",
+                "Generate an image using the currently available AI Studio model.",
+                [action],
+            )
+
+        if re.search(r"\b(render|export)\b", lowered):
+            if project_id is None or revision is None:
+                return self._blocked(
+                    normalized,
+                    "Rendering requires a project with saved editor state.",
+                    missing=["saved editor state"],
+                )
+            action = EditorRenderAction(
+                id=action_id,
+                type="editor.render",
+                arguments=EditorRenderArguments(project_id=project_id, expected_revision=revision),
+                reason="Submit the current authoritative editor revision for rendering.",
+                requires_confirmation=True,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="projects:update",
+                required_capability="editor.render",
+            )
+            return self._plan(
+                "Render project",
+                "Validate and submit the current editor revision to the existing render pipeline.",
+                [action],
+            )
+
+        split_match = re.search(
+            r"\bsplit\b.*?\b(?:at\s+)?(\d+(?:\.\d+)?)\s*(seconds?|secs?|s)\b",
+            lowered,
+        )
+        if split_match:
+            missing = self._editor_missing(project_id, revision, selected_clip)
+            if missing:
+                return self._blocked(
+                    normalized, "Select a saved timeline clip first.", missing=missing
+                )
+            action = EditorSplitClipAction(
+                id=action_id,
+                type="editor.split_clip",
+                arguments=EditorSplitClipArguments(
+                    project_id=project_id,
+                    clip_id=selected_clip,
+                    at_ms=round(float(split_match.group(1)) * 1_000),
+                    expected_revision=revision,
+                ),
+                reason="Split the selected clip at the requested timeline time.",
+                requires_confirmation=False,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="projects:update",
+                required_capability="editor.split_clip",
+            )
+            return self._plan(
+                "Split selected clip",
+                "Save a revision-safe split through the authoritative editor service.",
+                [action],
+            )
+
+        if re.search(r"\b(delete|remove)\b.*\b(selected\s+)?clip\b", lowered):
+            missing = self._editor_missing(project_id, revision, selected_clip)
+            if missing:
+                return self._blocked(
+                    normalized, "Select a saved timeline clip first.", missing=missing
+                )
+            action = EditorDeleteClipAction(
+                id=action_id,
+                type="editor.delete_clip",
+                arguments=EditorDeleteClipArguments(
+                    project_id=project_id,
+                    clip_id=selected_clip,
+                    expected_revision=revision,
+                ),
+                reason="Remove the selected clip from the authoritative timeline.",
+                requires_confirmation=True,
+                destructive=True,
+                external_side_effect=False,
+                required_permission="projects:update",
+                required_capability="editor.delete_clip",
+            )
+            return self._plan(
+                "Delete selected clip",
+                "Delete the selected clip after explicit confirmation.",
+                [action],
+            )
+
+        duration_match = re.search(
+            r"\b(?:last|duration|make)\b.*?(\d+(?:\.\d+)?)\s*(seconds?|secs?|s)\b",
+            lowered,
+        )
+        if duration_match and ("clip" in lowered or "image" in lowered):
+            missing = self._editor_missing(project_id, revision, selected_clip)
+            if missing:
+                return self._blocked(
+                    normalized, "Select a saved timeline clip first.", missing=missing
+                )
+            action = EditorSetDurationAction(
+                id=action_id,
+                type="editor.set_duration",
+                arguments=EditorSetDurationArguments(
+                    project_id=project_id,
+                    clip_id=selected_clip,
+                    duration_ms=round(float(duration_match.group(1)) * 1_000),
+                    expected_revision=revision,
+                ),
+                reason="Set the selected clip duration.",
+                requires_confirmation=False,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="projects:update",
+                required_capability="editor.set_duration",
+            )
+            return self._plan(
+                "Update clip duration",
+                "Save the requested duration through the authoritative editor service.",
+                [action],
+            )
+
+        if re.search(r"\badd\b.*\b(asset|image|video|audio)\b.*\b(timeline|editor)\b", lowered):
+            if project_id is None or revision is None or selected_asset is None:
+                return self._blocked(
+                    normalized,
+                    "Adding media requires a project, saved editor state, and selected asset.",
+                    missing=["project", "saved editor state", "asset"],
+                )
+            action = EditorAddClipAction(
+                id=action_id,
+                type="editor.add_clip",
+                arguments=EditorAddClipArguments(
+                    project_id=project_id,
+                    asset_id=selected_asset,
+                    expected_revision=revision,
+                ),
+                reason="Add the selected canonical asset to the timeline.",
+                requires_confirmation=False,
+                destructive=False,
+                external_side_effect=False,
+                required_permission="projects:update",
+                required_capability="editor.add_clip",
+            )
+            return self._plan(
+                "Add asset to timeline",
+                "Insert the selected project asset through the authoritative editor service.",
+                [action],
+            )
+
+        return self._blocked(
+            normalized,
+            "This request does not map to a currently registered Copilot action.",
+            unsupported=["natural-language intent"],
+        )
+
+    @staticmethod
+    def _editor_missing(project_id, revision, selected_clip) -> list[str]:
+        missing = []
+        if project_id is None:
+            missing.append("project")
+        if revision is None:
+            missing.append("saved editor state")
+        if selected_clip is None:
+            missing.append("selected clip")
+        return missing
+
+    @staticmethod
+    def _generation_prompt(request: str, media_word: str) -> str:
+        stripped = re.sub(
+            rf"(?i)^\s*(please\s+)?generate\s+(an?\s+)?{media_word}\s*(of|for|with|:)?\s*",
+            "",
+            request,
+        ).strip()
+        return stripped or request
+
+    @staticmethod
+    def _template_id(request: str) -> str | None:
+        match = re.search(
+            r"\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b",
+            request,
+            re.IGNORECASE,
+        )
+        return match.group(0) if match else None
+
+    @staticmethod
+    def _requested_unavailable_capability(request: str, context: CopilotContext) -> str | None:
+        requested = {
+            "transcrib": "ai.transcribe",
+            "upscal": "ai.upscale",
+            "remove background": "ai.remove_background",
+            "voice": "ai.generate_voice",
+            "music": "ai.generate_music",
+            "caption": "ai.transcribe",
+            "tiktok": "ai.transcribe",
+            "highlight": "ai.analyze",
+        }
+        for fragment, capability in requested.items():
+            if fragment in request and capability not in context.available_capabilities:
+                return capability
+        return None
+
+    @staticmethod
+    def _plan(intent: str, explanation: str, actions: list) -> CopilotPlan:
+        return CopilotPlan(
+            intent=intent,
+            explanation=explanation,
+            actions=actions,
+            executable=True,
+            requires_confirmation=any(action.requires_confirmation for action in actions),
+        )
+
+    @staticmethod
+    def _blocked(
+        intent: str,
+        explanation: str,
+        *,
+        missing: list[str] | None = None,
+        unsupported: list[str] | None = None,
+    ) -> CopilotPlan:
+        return CopilotPlan(
+            intent=intent[:200],
+            explanation=explanation,
+            actions=[],
+            missing_information=missing or [],
+            unsupported_capabilities=unsupported or [],
+            executable=False,
+            requires_confirmation=False,
+        )

app/copilot/repository.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+
+from app.copilot.errors import CopilotRunConflictError, CopilotRunNotFoundError
+from app.copilot.models import CopilotRunRecord
+from app.security.database import SecurityDatabase
+
+
+class CopilotRepository:
+    def __init__(self, database: SecurityDatabase) -> None:
+        self.database = database
+
+    async def create(self, record: CopilotRunRecord) -> tuple[CopilotRunRecord, bool]:
+        try:
+            async with self.database.tenant_session(
+                workspace_id=record.workspace_id, user_id=record.user_id
+            ) as session:
+                session.add(record)
+                await session.commit()
+                await session.refresh(record)
+                return record, True
+        except IntegrityError:
+            existing = await self.get_by_idempotency(
+                record.workspace_id, record.user_id, record.idempotency_key
+            )
+            if existing is None:
+                raise
+            if existing.request_fingerprint != record.request_fingerprint:
+                raise CopilotRunConflictError(
+                    "Idempotency-Key is already associated with another Copilot request."
+                )
+            return existing, False
+
+    async def get_by_idempotency(
+        self, workspace_id: str, user_id: str, key: str
+    ) -> CopilotRunRecord | None:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            return await session.scalar(
+                select(CopilotRunRecord).where(
+                    CopilotRunRecord.workspace_id == workspace_id,
+                    CopilotRunRecord.idempotency_key == key,
+                )
+            )
+
+    async def get(
+        self, workspace_id: str, user_id: str, run_id: str, *, lock: bool = False
+    ) -> CopilotRunRecord:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            statement = select(CopilotRunRecord).where(
+                CopilotRunRecord.id == run_id,
+                CopilotRunRecord.workspace_id == workspace_id,
+            )
+            if lock:
+                statement = statement.with_for_update()
+            record = await session.scalar(statement)
+            if record is None:
+                raise CopilotRunNotFoundError("Copilot run was not found in this workspace.")
+            return record
+
+    async def list(
+        self, workspace_id: str, user_id: str, *, offset: int, limit: int
+    ) -> list[CopilotRunRecord]:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            return list(
+                (
+                    await session.scalars(
+                        select(CopilotRunRecord)
+                        .where(CopilotRunRecord.workspace_id == workspace_id)
+                        .order_by(CopilotRunRecord.created_at.desc())
+                        .offset(offset)
+                        .limit(limit)
+                    )
+                ).all()
+            )
+
+    async def claim_execution(
+        self,
+        workspace_id: str,
+        user_id: str,
+        run_id: str,
+        *,
+        confirmed: bool,
+    ) -> CopilotRunRecord:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            record = await session.scalar(
+                select(CopilotRunRecord)
+                .where(
+                    CopilotRunRecord.id == run_id,
+                    CopilotRunRecord.workspace_id == workspace_id,
+                )
+                .with_for_update()
+            )
+            if record is None:
+                raise CopilotRunNotFoundError("Copilot run was not found in this workspace.")
+            if record.status != "plan_ready":
+                raise CopilotRunConflictError("Only a plan-ready Copilot run can be executed.")
+            now = datetime.now(timezone.utc)
+            record.status = "executing"
+            record.updated_at = now
+            if confirmed and record.confirmed_at is None:
+                record.confirmed_at = now
+            await session.commit()
+            await session.refresh(record)
+            return record
+
+    async def cancel_before_execution(
+        self,
+        workspace_id: str,
+        user_id: str,
+        run_id: str,
+    ) -> tuple[CopilotRunRecord, bool]:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            record = await session.scalar(
+                select(CopilotRunRecord)
+                .where(
+                    CopilotRunRecord.id == run_id,
+                    CopilotRunRecord.workspace_id == workspace_id,
+                )
+                .with_for_update()
+            )
+            if record is None:
+                raise CopilotRunNotFoundError("Copilot run was not found in this workspace.")
+            if record.status in {"completed", "partial", "failed", "cancelled"}:
+                return record, False
+            if record.status == "executing":
+                raise CopilotRunConflictError(
+                    "This action batch is already executing; cancel its durable child job directly."
+                )
+            now = datetime.now(timezone.utc)
+            record.status = "cancelled"
+            record.current_action_id = None
+            record.summary = "Copilot run cancelled before execution."
+            record.updated_at = now
+            record.completed_at = now
+            await session.commit()
+            await session.refresh(record)
+            return record, True
+
+    async def update(
+        self,
+        workspace_id: str,
+        user_id: str,
+        run_id: str,
+        *,
+        status: str,
+        current_action_id: str | None = None,
+        results: list[dict[str, object]] | None = None,
+        summary: str | None = None,
+        error_code: str | None = None,
+        error_message: str | None = None,
+        confirmed: bool = False,
+        terminal: bool = False,
+    ) -> CopilotRunRecord:
+        async with self.database.tenant_session(
+            workspace_id=workspace_id, user_id=user_id
+        ) as session:
+            record = await session.scalar(
+                select(CopilotRunRecord)
+                .where(
+                    CopilotRunRecord.id == run_id,
+                    CopilotRunRecord.workspace_id == workspace_id,
+                )
+                .with_for_update()
+            )
+            if record is None:
+                raise CopilotRunNotFoundError("Copilot run was not found in this workspace.")
+            now = datetime.now(timezone.utc)
+            record.status = status
+            record.current_action_id = current_action_id
+            if results is not None:
+                record.results_json = results
+            record.summary = summary
+            record.error_code = error_code
+            record.error_message = error_message
+            if confirmed and record.confirmed_at is None:
+                record.confirmed_at = now
+            record.updated_at = now
+            if terminal:
+                record.completed_at = now
+            await session.commit()
+            await session.refresh(record)
+            return record

app/copilot/schemas.py

@@ -0,0 +1,439 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated, Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from app.social.schemas.posts import SocialPostCreate
+from app.social.schemas.scheduling import SocialScheduleCreate
+from app.templates.marketplace_schemas import SlotBinding
+
+CopilotRunStatus = Literal[
+    "plan_ready",
+    "blocked",
+    "executing",
+    "completed",
+    "partial",
+    "failed",
+    "cancelled",
+]
+CopilotActionStatus = Literal["pending", "running", "completed", "failed", "cancelled"]
+
+
+class CopilotEditorSummary(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    revision: int = Field(ge=1)
+    duration_ms: int = Field(ge=0)
+    track_count: int = Field(ge=0, le=32)
+    clip_count: int = Field(ge=0, le=500)
+
+
+class CopilotContextInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    project_id: UUID | None = None
+    selected_asset_ids: list[UUID] = Field(default_factory=list, max_length=20)
+    selected_clip_ids: list[str] = Field(default_factory=list, max_length=20)
+    active_tool: str | None = Field(default=None, max_length=100)
+    editor_summary: CopilotEditorSummary | None = None
+
+
+class CopilotContext(CopilotContextInput):
+    workspace_id: str
+    available_capabilities: list[str] = Field(default_factory=list, max_length=100)
+
+
+class ProjectOpenArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    project_id: UUID
+
+
+class AssetSelectArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    asset_id: UUID
+    project_id: UUID | None = None
+
+
+class AiGenerateImageArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    prompt: str = Field(min_length=1, max_length=4_000)
+    project_id: UUID | None = None
+    source_asset_id: UUID | None = None
+    model: str | None = Field(default=None, max_length=255)
+
+
+class AiGenerateVideoArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    prompt: str = Field(min_length=1, max_length=4_000)
+    project_id: UUID | None = None
+    source_asset_id: UUID
+    model: str | None = Field(default=None, max_length=255)
+
+
+class EditorSplitClipArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    project_id: UUID
+    clip_id: str = Field(min_length=1, max_length=128)
+    at_ms: int = Field(gt=0)
+    expected_revision: int = Field(ge=1)
+
+
+class EditorDeleteClipArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    project_id: UUID
+    clip_id: str = Field(min_length=1, max_length=128)
+    expected_revision: int = Field(ge=1)
+
+
+class EditorSetDurationArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    project_id: UUID
+    clip_id: str = Field(min_length=1, max_length=128)
+    duration_ms: int = Field(gt=0)
+    expected_revision: int = Field(ge=1)
+
+
+class EditorAddClipArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    project_id: UUID
+    asset_id: UUID
+    expected_revision: int = Field(ge=1)
+    duration_ms: int = Field(default=5_000, gt=0)
+
+
+class EditorRenderArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    project_id: UUID
+    expected_revision: int = Field(ge=1)
+
+class TemplateSearchArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    query: str = Field(min_length=1, max_length=200)
+    category: str | None = Field(default=None, max_length=50)
+
+
+class TemplateGetArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    template_id: UUID
+
+
+class TemplateApplyArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    template_id: UUID
+    project_id: UUID
+    template_version_id: UUID | None = None
+    slot_bindings: dict[str, SlotBinding] = Field(default_factory=dict, max_length=100)
+
+
+class TemplateCreateProjectArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    template_id: UUID
+    project_name: str = Field(min_length=1, max_length=200)
+    template_version_id: UUID | None = None
+    slot_bindings: dict[str, SlotBinding] = Field(default_factory=dict, max_length=100)
+
+
+class PublishingValidateArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    post_id: UUID
+
+
+class PublishingCreatePostArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    post: SocialPostCreate
+
+
+class PublishingScheduleArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    post_id: UUID
+    schedule: SocialScheduleCreate
+
+
+class PublishingPublishArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    post_id: UUID
+
+
+class PublishingCancelArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    post_id: UUID
+
+
+class AnalyticsOverviewArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    project_id: UUID | None = None
+    provider: str | None = Field(default=None, max_length=32)
+    metric: Literal["views", "impressions", "likes", "comments", "shares", "engagement_rate"] = (
+        "views"
+    )
+    timezone: str = Field(default="UTC", min_length=1, max_length=100)
+
+
+class AnalyticsSyncArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    project_id: UUID | None = None
+    provider: str | None = Field(default=None, max_length=32)
+    timezone: str = Field(default="UTC", min_length=1, max_length=100)
+
+
+class _ActionBase(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(min_length=1, max_length=64)
+    reason: str = Field(min_length=1, max_length=500)
+    requires_confirmation: bool
+    destructive: bool
+    external_side_effect: bool
+    required_permission: str = Field(min_length=1, max_length=100)
+    required_capability: str = Field(min_length=1, max_length=100)
+
+
+class ProjectOpenAction(_ActionBase):
+    type: Literal["project.open"]
+    arguments: ProjectOpenArguments
+
+
+class AssetSelectAction(_ActionBase):
+    type: Literal["asset.select"]
+    arguments: AssetSelectArguments
+
+
+class AiGenerateImageAction(_ActionBase):
+    type: Literal["ai.generate_image"]
+    arguments: AiGenerateImageArguments
+
+
+class AiGenerateVideoAction(_ActionBase):
+    type: Literal["ai.generate_video"]
+    arguments: AiGenerateVideoArguments
+
+
+class EditorSplitClipAction(_ActionBase):
+    type: Literal["editor.split_clip"]
+    arguments: EditorSplitClipArguments
+
+
+class EditorDeleteClipAction(_ActionBase):
+    type: Literal["editor.delete_clip"]
+    arguments: EditorDeleteClipArguments
+
+
+class EditorSetDurationAction(_ActionBase):
+    type: Literal["editor.set_duration"]
+    arguments: EditorSetDurationArguments
+
+
+class EditorAddClipAction(_ActionBase):
+    type: Literal["editor.add_clip"]
+    arguments: EditorAddClipArguments
+
+
+class EditorRenderAction(_ActionBase):
+    type: Literal["editor.render"]
+    arguments: EditorRenderArguments
+
+
+class ShareProjectArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    project_id: str
+    user_id: str
+    role: str
+
+class SubmitForReviewArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    project_id: str
+    workflow_id: str
+
+class ProjectActivitySummarizeArguments(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    project_id: str
+
+class ShareProjectAction(_ActionBase):
+    type: Literal["project.share"]
+    arguments: ShareProjectArguments
+
+class SubmitForReviewAction(_ActionBase):
+    type: Literal["review.submit"]
+    arguments: SubmitForReviewArguments
+
+class ProjectActivitySummarizeAction(_ActionBase):
+    type: Literal["project_activity.summarize"]
+    arguments: ProjectActivitySummarizeArguments
+
+
+class TemplateSearchAction(_ActionBase):
+    type: Literal["template.search"]
+    arguments: TemplateSearchArguments
+
+
+class TemplateGetAction(_ActionBase):
+    type: Literal["template.get"]
+    arguments: TemplateGetArguments
+
+
+class TemplateApplyAction(_ActionBase):
+    type: Literal["template.apply"]
+    arguments: TemplateApplyArguments
+
+
+class TemplateCreateProjectAction(_ActionBase):
+    type: Literal["template.create_project"]
+    arguments: TemplateCreateProjectArguments
+
+
+class PublishingValidateAction(_ActionBase):
+    type: Literal["publishing.validate"]
+    arguments: PublishingValidateArguments
+
+
+class PublishingCreatePostAction(_ActionBase):
+    type: Literal["publishing.create_post"]
+    arguments: PublishingCreatePostArguments
+
+
+class PublishingScheduleAction(_ActionBase):
+    type: Literal["publishing.schedule"]
+    arguments: PublishingScheduleArguments
+
+
+class PublishingPublishAction(_ActionBase):
+    type: Literal["publishing.publish"]
+    arguments: PublishingPublishArguments
+
+
+class PublishingCancelAction(_ActionBase):
+    type: Literal["publishing.cancel"]
+    arguments: PublishingCancelArguments
+
+
+class AnalyticsOverviewAction(_ActionBase):
+    type: Literal["analytics.overview"]
+    arguments: AnalyticsOverviewArguments
+
+
+class AnalyticsSyncAction(_ActionBase):
+    type: Literal["analytics.sync"]
+    arguments: AnalyticsSyncArguments
+
+
+CopilotAction = Annotated[
+    ProjectOpenAction
+    | AssetSelectAction
+    | AiGenerateImageAction
+    | AiGenerateVideoAction
+    | EditorSplitClipAction
+    | EditorDeleteClipAction
+    | EditorSetDurationAction
+    | EditorAddClipAction
+    | EditorRenderAction
+    | ShareProjectAction
+    | SubmitForReviewAction
+    | ProjectActivitySummarizeAction
+    | TemplateSearchAction
+    | TemplateGetAction
+    | TemplateApplyAction
+    | TemplateCreateProjectAction
+    | PublishingValidateAction
+    | PublishingCreatePostAction
+    | PublishingScheduleAction
+    | PublishingPublishAction
+    | PublishingCancelAction
+    | AnalyticsOverviewAction
+    | AnalyticsSyncAction,
+    Field(discriminator="type"),
+]
+
+
+class CopilotPlan(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    intent: str = Field(min_length=1, max_length=200)
+    explanation: str = Field(min_length=1, max_length=1_000)
+    actions: list[CopilotAction] = Field(default_factory=list, max_length=20)
+    missing_information: list[str] = Field(default_factory=list, max_length=20)
+    unsupported_capabilities: list[str] = Field(default_factory=list, max_length=20)
+    executable: bool
+    requires_confirmation: bool
+
+    @model_validator(mode="after")
+    def validate_execution(self) -> "CopilotPlan":
+        if self.executable and not self.actions:
+            raise ValueError("Executable plans require at least one action")
+        if self.requires_confirmation != any(
+            action.requires_confirmation for action in self.actions
+        ):
+            raise ValueError("Plan confirmation state must match its actions")
+        return self
+
+
+class CopilotActionResult(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    action_id: str
+    action_type: str
+    status: CopilotActionStatus
+    summary: str = Field(max_length=1_000)
+    resource_type: str | None = Field(default=None, max_length=100)
+    resource_id: str | None = Field(default=None, max_length=255)
+    retryable: bool = False
+    error_code: str | None = Field(default=None, max_length=100)
+
+
+class CopilotRunCreate(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    request: str = Field(min_length=1, max_length=4_000)
+    context: CopilotContextInput = Field(default_factory=CopilotContextInput)
+
+
+class CopilotExecuteRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    confirmed: bool = False
+
+
+class CopilotRun(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    project_id: str | None
+    status: CopilotRunStatus
+    request: str
+    context: CopilotContext
+    plan: CopilotPlan
+    current_action_id: str | None
+    results: list[CopilotActionResult]
+    summary: str | None
+    error_code: str | None
+    error_message: str | None
+    created_at: datetime
+    updated_at: datetime
+    completed_at: datetime | None
+
+
+class CopilotRunList(BaseModel):
+    items: list[CopilotRun]
+    offset: int
+    limit: int
+
+
+class CopilotActionCapability(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    type: str
+    description: str
+    required_permission: str
+    required_capability: str
+    destructive: bool
+    external_side_effect: bool
+    requires_confirmation: bool
+    available: bool
+
+
+class CopilotCapabilities(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    available: bool
+    planner: Literal["deterministic"]
+    actions: list[CopilotActionCapability]
+    permissions: list[str]

app/copilot/service.py

@@ -0,0 +1,499 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+
+from app.ai.service import AiStudioService
+from app.copilot.actions import CopilotActionRegistry
+from app.copilot.errors import (
+    CopilotConfirmationRequiredError,
+    CopilotInvalidRequestError,
+    CopilotRunConflictError,
+)
+from app.copilot.models import CopilotRunRecord
+from app.copilot.planner import CopilotPlanner
+from app.copilot.repository import CopilotRepository
+from app.copilot.schemas import (
+    CopilotCapabilities,
+    CopilotContext,
+    CopilotContextInput,
+    CopilotEditorSummary,
+    CopilotExecuteRequest,
+    CopilotPlan,
+    CopilotRun,
+    CopilotRunCreate,
+    CopilotRunList,
+)
+from app.core.exceptions import MediaAPIError
+from app.core.logger import get_logger
+from app.projects.errors import ProjectEditorNotFoundError
+from app.projects.services.editor_service import ProjectEditorService
+from app.projects.services.project_service import ProjectService
+from app.security.assets import CanonicalAssetNotFoundError, CanonicalAssetService
+from app.security.audit import AuditService
+
+logger = get_logger(__name__)
+
+
+class CopilotService:
+    def __init__(
+        self,
+        *,
+        repository: CopilotRepository,
+        planner: CopilotPlanner,
+        actions: CopilotActionRegistry,
+        projects: ProjectService,
+        assets: CanonicalAssetService,
+        editor: ProjectEditorService,
+        ai: AiStudioService,
+        audit: AuditService,
+    ) -> None:
+        self.repository = repository
+        self.planner = planner
+        self.actions = actions
+        self.projects = projects
+        self.assets = assets
+        self.editor = editor
+        self.ai = ai
+        self.audit = audit
+
+    async def capabilities(
+        self, *, workspace_id: str, user_id: str, context: CopilotContextInput
+    ) -> CopilotCapabilities:
+        bounded = await self.build_context(
+            workspace_id=workspace_id, user_id=user_id, supplied=context
+        )
+        available = set(bounded.available_capabilities)
+        return CopilotCapabilities(
+            available=True,
+            planner="deterministic",
+            actions=self.actions.capabilities(available),
+            permissions=["copilot:read", "copilot:execute"],
+        )
+
+    async def build_context(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        supplied: CopilotContextInput,
+    ) -> CopilotContext:
+        project_id = str(supplied.project_id) if supplied.project_id else None
+        capabilities = {
+            "project.open",
+            "asset.select",
+            "template.search",
+            "template.get",
+            "template.apply",
+            "template.create_project",
+            "publishing.validate",
+            "publishing.create_post",
+            "publishing.schedule",
+            "publishing.publish",
+            "publishing.cancel",
+            "analytics.overview",
+            "analytics.sync",
+        }
+        editor_summary = None
+        editor_document = None
+        if project_id:
+            await self.projects.get(
+                workspace_id=workspace_id, user_id=user_id, project_id=project_id
+            )
+            try:
+                editor = await self.editor.get(
+                    workspace_id=workspace_id,
+                    user_id=user_id,
+                    project_id=project_id,
+                )
+                editor_document = editor.state
+                editor_summary = CopilotEditorSummary(
+                    revision=editor.revision,
+                    duration_ms=editor.state.duration_ms(),
+                    track_count=len(editor.state.timeline.tracks),
+                    clip_count=sum(len(track.clips) for track in editor.state.timeline.tracks),
+                )
+                capabilities.update(
+                    {
+                        "editor.split_clip",
+                        "editor.delete_clip",
+                        "editor.set_duration",
+                        "editor.add_clip",
+                        "editor.render",
+                    }
+                )
+            except ProjectEditorNotFoundError:
+                editor_summary = None
+        selected_assets = []
+        for asset_id in supplied.selected_asset_ids:
+            try:
+                asset = await self.assets.get_owned_by_id(
+                    workspace_id=workspace_id,
+                    user_id=user_id,
+                    asset_id=str(asset_id),
+                )
+            except CanonicalAssetNotFoundError as exc:
+                raise CopilotInvalidRequestError(
+                    "A selected asset is not available in this workspace."
+                ) from exc
+            if project_id and asset.project_id != project_id:
+                raise CopilotInvalidRequestError(
+                    "Every selected asset must belong to the selected project."
+                )
+            selected_assets.append(asset.id)
+        selected_clips = list(dict.fromkeys(supplied.selected_clip_ids))
+        if selected_clips:
+            if editor_document is None:
+                raise CopilotInvalidRequestError("Selected clips require saved editor state.")
+            known = {clip.id for track in editor_document.timeline.tracks for clip in track.clips}
+            if any(clip_id not in known for clip_id in selected_clips):
+                raise CopilotInvalidRequestError(
+                    "A selected clip is not present in the authoritative editor state."
+                )
+        ai_capabilities = self.ai.capabilities()
+        for tool in ai_capabilities.tools:
+            if tool.available:
+                capabilities.add(f"ai.{tool.operation.removeprefix('generate_')}")
+                capabilities.add(f"ai.{tool.operation}")
+        return CopilotContext(
+            workspace_id=workspace_id,
+            project_id=supplied.project_id,
+            selected_asset_ids=selected_assets,
+            selected_clip_ids=selected_clips,
+            active_tool=supplied.active_tool,
+            editor_summary=editor_summary,
+            available_capabilities=sorted(capabilities),
+        )
+
+    async def create_run(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        payload: CopilotRunCreate,
+        idempotency_key: str,
+    ) -> CopilotRun:
+        key = idempotency_key.strip()
+        if not key or len(key) > 255:
+            raise CopilotInvalidRequestError("A bounded Idempotency-Key is required.")
+        context = await self.build_context(
+            workspace_id=workspace_id, user_id=user_id, supplied=payload.context
+        )
+        fingerprint = hashlib.sha256(
+            json.dumps(
+                {
+                    "request": payload.request,
+                    "context": context.model_dump(mode="json"),
+                },
+                sort_keys=True,
+                separators=(",", ":"),
+            ).encode()
+        ).hexdigest()
+        plan = self.planner.plan(payload.request, context)
+        self.actions.validate_plan(plan.actions)
+        record = CopilotRunRecord(
+            workspace_id=workspace_id,
+            user_id=user_id,
+            project_id=str(context.project_id) if context.project_id else None,
+            idempotency_key=key,
+            request_fingerprint=fingerprint,
+            request_text=payload.request,
+            context_json=context.model_dump(mode="json"),
+            plan_json=plan.model_dump(mode="json"),
+            status="plan_ready" if plan.executable else "blocked",
+            results_json=[],
+        )
+        created, is_new = await self.repository.create(record)
+        if is_new:
+            await self.audit.record_event(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                api_key_id=api_key_id,
+                request_id=request_id,
+                event_type="copilot.run_started",
+                entity_type="copilot_run",
+                entity_id=created.id,
+                metadata={"project_id": created.project_id},
+            )
+            await self.audit.record_event(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                api_key_id=api_key_id,
+                request_id=request_id,
+                event_type="copilot.plan_created",
+                entity_type="copilot_run",
+                entity_id=created.id,
+                metadata={
+                    "action_count": len(plan.actions),
+                    "requires_confirmation": plan.requires_confirmation,
+                    "executable": plan.executable,
+                },
+            )
+        logger.info(
+            "copilot plan created",
+            extra={
+                "run_id": created.id,
+                "project_id": created.project_id,
+                "status": created.status,
+                "action_count": len(plan.actions),
+            },
+        )
+        return self._response(created)
+
+    async def execute(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        run_id: str,
+        payload: CopilotExecuteRequest,
+        permissions: frozenset[str],
+    ) -> CopilotRun:
+        record = await self.repository.get(workspace_id, user_id, run_id)
+        if record.status not in {"plan_ready"}:
+            raise CopilotRunConflictError("Only a plan-ready Copilot run can be executed.")
+        plan = CopilotPlan.model_validate(record.plan_json)
+        self.actions.validate_plan(plan.actions)
+        if not plan.executable:
+            raise CopilotRunConflictError("This Copilot plan is not executable.")
+        if plan.requires_confirmation and not payload.confirmed:
+            raise CopilotConfirmationRequiredError(
+                "Explicit confirmation is required before this plan can run."
+            )
+        record = await self.repository.claim_execution(
+            workspace_id,
+            user_id,
+            run_id,
+            confirmed=payload.confirmed,
+        )
+        results = []
+        started = time.monotonic()
+        available = set(CopilotContext.model_validate(record.context_json).available_capabilities)
+        for action in plan.actions:
+            await self.repository.update(
+                workspace_id,
+                user_id,
+                run_id,
+                status="executing",
+                current_action_id=action.id,
+                results=[item.model_dump(mode="json") for item in results],
+            )
+            await self.audit.record_event(
+                workspace_id=workspace_id,
+                user_id=user_id,
+                api_key_id=api_key_id,
+                request_id=request_id,
+                event_type="copilot.action_started",
+                entity_type="copilot_run",
+                entity_id=run_id,
+                metadata={"action_id": action.id, "action_type": action.type},
+            )
+            try:
+                result = await self.actions.execute(
+                    action,
+                    workspace_id=workspace_id,
+                    user_id=user_id,
+                    api_key_id=api_key_id,
+                    request_id=request_id,
+                    run_id=run_id,
+                    permissions=permissions,
+                    available_capabilities=available,
+                )
+                results.append(result)
+                await self.audit.record_event(
+                    workspace_id=workspace_id,
+                    user_id=user_id,
+                    api_key_id=api_key_id,
+                    request_id=request_id,
+                    event_type="copilot.action_completed",
+                    entity_type="copilot_run",
+                    entity_id=run_id,
+                    metadata={
+                        "action_id": action.id,
+                        "action_type": action.type,
+                        "resource_type": result.resource_type,
+                        "resource_id": result.resource_id,
+                    },
+                )
+            except Exception as exc:
+                if isinstance(exc, MediaAPIError):
+                    error_code = exc.code
+                    error_message = exc.message
+                else:
+                    error_code = "COPILOT_ACTION_FAILED"
+                    error_message = "The Copilot action failed unexpectedly."
+                    logger.error(
+                        "copilot action failed unexpectedly",
+                        extra={
+                            "run_id": run_id,
+                            "project_id": record.project_id,
+                            "action_id": action.id,
+                            "action_type": action.type,
+                            "error_category": error_code,
+                        },
+                    )
+                results.append(
+                    self._failed_result(
+                        action.id,
+                        action.type,
+                        error_message,
+                        error_code,
+                    )
+                )
+                await self.audit.record_event(
+                    workspace_id=workspace_id,
+                    user_id=user_id,
+                    api_key_id=api_key_id,
+                    request_id=request_id,
+                    event_type="copilot.action_failed",
+                    entity_type="copilot_run",
+                    entity_id=run_id,
+                    metadata={
+                        "action_id": action.id,
+                        "action_type": action.type,
+                        "error_code": error_code,
+                    },
+                )
+                break
+        completed = sum(item.status == "completed" for item in results)
+        failed = sum(item.status == "failed" for item in results)
+        if failed and completed:
+            status = "partial"
+            summary = (
+                f"{completed} of {len(plan.actions)} actions completed; "
+                "the remaining workflow stopped after a failure."
+            )
+            event = "copilot.run_failed"
+        elif failed:
+            status = "failed"
+            summary = "The Copilot action failed before the workflow completed."
+            event = "copilot.run_failed"
+        else:
+            status = "completed"
+            summary = f"{completed} action{'s' if completed != 1 else ''} completed."
+            event = "copilot.run_completed"
+        updated = await self.repository.update(
+            workspace_id,
+            user_id,
+            run_id,
+            status=status,
+            current_action_id=None,
+            results=[item.model_dump(mode="json") for item in results],
+            summary=summary,
+            error_code=results[-1].error_code if failed else None,
+            error_message=results[-1].summary if failed else None,
+            terminal=True,
+        )
+        await self.audit.record_event(
+            workspace_id=workspace_id,
+            user_id=user_id,
+            api_key_id=api_key_id,
+            request_id=request_id,
+            event_type=event,
+            entity_type="copilot_run",
+            entity_id=run_id,
+            metadata={
+                "status": status,
+                "completed_actions": completed,
+                "failed_actions": failed,
+            },
+        )
+        logger.info(
+            "copilot run finished",
+            extra={
+                "run_id": run_id,
+                "project_id": record.project_id,
+                "status": status,
+                "duration_ms": round((time.monotonic() - started) * 1_000),
+            },
+        )
+        return self._response(updated)
+
+    async def cancel(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        api_key_id: str,
+        request_id: str,
+        run_id: str,
+    ) -> CopilotRun:
+        updated, changed = await self.repository.cancel_before_execution(
+            workspace_id,
+            user_id,
+            run_id,
+        )
+        if not changed:
+            return self._response(updated)
+        await self.audit.record_event(
+            workspace_id=workspace_id,
+            user_id=user_id,
+            api_key_id=api_key_id,
+            request_id=request_id,
+            event_type="copilot.run_cancelled",
+            entity_type="copilot_run",
+            entity_id=run_id,
+            metadata={"project_id": updated.project_id},
+        )
+        return self._response(updated)
+
+    async def get(self, *, workspace_id: str, user_id: str, run_id: str) -> CopilotRun:
+        return self._response(await self.repository.get(workspace_id, user_id, run_id))
+
+    async def list(
+        self,
+        *,
+        workspace_id: str,
+        user_id: str,
+        offset: int,
+        limit: int,
+    ) -> CopilotRunList:
+        records = await self.repository.list(workspace_id, user_id, offset=offset, limit=limit)
+        return CopilotRunList(
+            items=[self._response(record) for record in records],
+            offset=offset,
+            limit=limit,
+        )
+
+    @staticmethod
+    def _failed_result(action_id: str, action_type: str, message: str, error_code: str):
+        from app.copilot.schemas import CopilotActionResult
+
+        return CopilotActionResult(
+            action_id=action_id,
+            action_type=action_type,
+            status="failed",
+            summary=message[:1_000],
+            error_code=error_code,
+            retryable=isinstance(error_code, str)
+            and error_code
+            in {
+                "GENERATION_PROVIDER_UNAVAILABLE",
+                "RATE_LIMIT_EXCEEDED",
+                "PROJECT_EDITOR_REVISION_CONFLICT",
+            },
+        )
+
+    @staticmethod
+    def _response(record: CopilotRunRecord) -> CopilotRun:
+        return CopilotRun(
+            id=record.id,
+            project_id=record.project_id,
+            status=record.status,
+            request=record.request_text,
+            context=CopilotContext.model_validate(record.context_json),
+            plan=CopilotPlan.model_validate(record.plan_json),
+            current_action_id=record.current_action_id,
+            results=record.results_json or [],
+            summary=record.summary,
+            error_code=record.error_code,
+            error_message=record.error_message,
+            created_at=record.created_at,
+            updated_at=record.updated_at,
+            completed_at=record.completed_at,
+        )

app/core/config.py

@@ -5,7 +5,7 @@ from functools import lru_cache
 from pathlib import Path
 from urllib.parse import urlparse
 
-from pydantic import Field, SecretStr, field_validator
+from pydantic import Field, SecretStr, field_validator, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 DEFAULT_TEMPLATE_DIR = Path(__file__).resolve().parents[1] / "templates" / "categories"
@@ -20,8 +20,10 @@ class Settings(BaseSettings):
 
     app_name: str = "MediaRouter"
     app_version: str = "1.0.0"
+    app_environment: str = "development"
     host: str = "0.0.0.0"
     port: int = 7860
+    cors_allowed_origins: str = ""
     temp_dir: Path = Path("./temp")
     output_dir: Path = Path("./outputs")
     template_dir: Path = DEFAULT_TEMPLATE_DIR
@@ -40,6 +42,11 @@ class Settings(BaseSettings):
     ffprobe_binary: str = "ffprobe"
     auth_enabled: bool = True
     database_url: str = "sqlite+aiosqlite:///./data/mediarouter.db"
+    # Security/tenant schema creation is automatic only for SQLite local
+    # development. PostgreSQL deployments must apply SQL migrations explicitly.
+    security_auto_migrate: bool = False
+    security_database_role: str = ""
+    security_enforce_rls: bool = True
     auth_role_scopes: dict[str, list[str]] = Field(default_factory=dict)
     auth_bootstrap_key_hash: str = ""
     auth_bootstrap_key_prefix: str = ""
@@ -49,9 +56,7 @@ class Settings(BaseSettings):
     auth_default_requests_per_minute: int = Field(default=100, ge=1, le=1_000_000)
     auth_default_concurrent_jobs: int = Field(default=10, ge=1, le=10_000)
     auth_default_uploads_per_hour: int = Field(default=20, ge=1, le=1_000_000)
-    auth_default_processing_bytes_per_day: int = Field(
-        default=107_374_182_400, ge=1_048_576
-    )
+    auth_default_processing_bytes_per_day: int = Field(default=107_374_182_400, ge=1_048_576)
     auth_trust_proxy_headers: bool = True
     mcp_stdio_api_key: SecretStr | None = None
     # Social Automation foundation. The existing database remains the default
@@ -59,6 +64,12 @@ class Settings(BaseSettings):
     # dedicated async SQLAlchemy URL and apply the SQL migration out-of-band.
     social_enabled: bool = True
     social_database_url: str = ""
+    # API requests use SOCIAL_DATABASE_URL with a non-BYPASSRLS role. Workers
+    # use a separate, backend-only connection with the trusted role below.
+    social_worker_database_url: str = ""
+    social_tenant_database_role: str = ""
+    social_worker_database_role: str = ""
+    social_enforce_rls: bool = True
     social_auto_migrate: bool = False
     social_worker_enabled: bool = True
     social_scheduler_interval_seconds: int = Field(default=30, ge=5, le=3600)
@@ -94,9 +105,7 @@ class Settings(BaseSettings):
     # Direct Post requires TikTok Content Posting approval and an audited app.
     # Keep it fail-closed until an operator has confirmed that access.
     tiktok_direct_post_enabled: bool = False
-    tiktok_upload_chunk_bytes: int = Field(
-        default=10_000_000, ge=5_000_000, le=64_000_000
-    )
+    tiktok_upload_chunk_bytes: int = Field(default=10_000_000, ge=5_000_000, le=64_000_000)
     tiktok_request_timeout_seconds: float = Field(default=60.0, gt=0, le=600)
     tiktok_processing_poll_seconds: int = Field(default=30, ge=5, le=3600)
     linkedin_client_id: str = ""
@@ -107,15 +116,9 @@ class Settings(BaseSettings):
     # the operator has confirmed the application products and write scopes in
     # LinkedIn Developer Portal.
     linkedin_publishing_enabled: bool = False
-    linkedin_request_timeout_seconds: float = Field(
-        default=60.0, gt=0, le=600
-    )
-    linkedin_media_processing_poll_seconds: int = Field(
-        default=5, ge=1, le=300
-    )
-    linkedin_media_processing_timeout_seconds: int = Field(
-        default=600, ge=30, le=3600
-    )
+    linkedin_request_timeout_seconds: float = Field(default=60.0, gt=0, le=600)
+    linkedin_media_processing_poll_seconds: int = Field(default=5, ge=1, le=300)
+    linkedin_media_processing_timeout_seconds: int = Field(default=600, ge=30, le=3600)
     x_client_id: str = ""
     x_client_secret: SecretStr | None = None
     # Exact OAuth 2.0 callback registered for the confidential X Web App.
@@ -132,6 +135,45 @@ class Settings(BaseSettings):
     whatsapp_client_id: str = ""
     whatsapp_client_secret: SecretStr | None = None
     social_oauth_redirect_base_url: str = ""
+    # Provider-neutral generation runtime. Providers remain optional and their
+    # worker endpoints/tokens stay server-side only.
+    generation_enabled: bool = True
+    generation_job_retry_limit: int = Field(default=3, ge=0, le=20)
+    # Shared remote-generation worker transport defaults. These do not enable
+    # a provider and intentionally contain no worker URL or credentials.
+    ai_worker_connect_timeout_seconds: float = Field(default=10.0, gt=0, le=300)
+    ai_worker_request_timeout_seconds: float = Field(default=60.0, gt=0, le=3600)
+    ai_worker_read_timeout_seconds: float = Field(default=300.0, gt=0, le=7200)
+    ai_worker_max_retries: int = Field(default=3, ge=0, le=10)
+    ai_worker_retry_backoff_seconds: float = Field(default=0.5, ge=0, le=60)
+    # WAN is optional.  These values remain backend-only and are deliberately
+    # not validated at Settings construction time: a bad optional worker
+    # configuration must leave WAN unavailable without preventing unrelated
+    # MediaRouter services from starting.
+    wan_space_url: str = ""
+    wan_space_token: SecretStr | None = None
+    # Optional authenticated FLUX.2 Klein worker. Invalid configuration keeps
+    # FLUX unavailable without affecting startup or other providers.
+    flux_space_url: str = ""
+    flux_space_token: SecretStr | None = None
+    generation_worker_enabled: bool = True
+    generation_worker_interval_seconds: float = Field(default=5.0, ge=0.5, le=3600)
+    generation_worker_poll_backoff_seconds: float = Field(default=2.0, ge=0.5, le=300)
+    generation_worker_batch_size: int = Field(default=8, ge=1, le=100)
+    generation_job_stale_after_seconds: int = Field(default=900, ge=60, le=86_400)
+    # Content Studio persistence/render safety limits. Rendering is optional
+    # infrastructure; disabling its worker never prevents API startup.
+    editor_state_max_bytes: int = Field(default=1_048_576, ge=16_384, le=16_777_216)
+    render_worker_enabled: bool = True
+    render_worker_interval_seconds: float = Field(default=2.0, ge=0.5, le=3600)
+    render_job_stale_after_seconds: int = Field(default=900, ge=60, le=86_400)
+    render_job_timeout_seconds: int = Field(default=7200, ge=60, le=86_400)
+    render_job_retry_limit: int = Field(default=2, ge=0, le=10)
+    render_max_active_jobs_per_project: int = Field(default=1, ge=1, le=10)
+    render_max_tracks: int = Field(default=32, ge=1, le=256)
+    render_max_clips: int = Field(default=500, ge=1, le=10_000)
+    render_max_duration_seconds: int = Field(default=3600, ge=1, le=21_600)
+    render_max_input_bytes: int = Field(default=4_294_967_296, ge=1_048_576)
 
     @field_validator("whisper_model")
     @classmethod
@@ -150,6 +192,107 @@ class Settings(BaseSettings):
             raise ValueError(f"LOG_LEVEL must be one of: {', '.join(sorted(allowed))}")
         return normalized
 
+    @field_validator("app_environment")
+    @classmethod
+    def normalize_app_environment(cls, value: str) -> str:
+        normalized = value.strip().lower()
+        if normalized not in {"development", "test", "production"}:
+            raise ValueError("APP_ENVIRONMENT must be development, test, or production")
+        return normalized
+
+    @property
+    def allowed_cors_origins(self) -> tuple[str, ...]:
+        """Return validated, normalized origins for Starlette CORS middleware."""
+
+        origins: list[str] = []
+        for configured in self.cors_allowed_origins.split(","):
+            origin = configured.strip().rstrip("/")
+            if not origin:
+                continue
+            parsed = urlparse(origin)
+            if (
+                "*" in origin
+                or parsed.scheme not in {"http", "https"}
+                or not parsed.netloc
+                or parsed.username
+                or parsed.password
+                or parsed.path
+                or parsed.params
+                or parsed.query
+                or parsed.fragment
+            ):
+                raise ValueError(
+                    "CORS_ALLOWED_ORIGINS must contain comma-separated HTTP(S) origins"
+                )
+            if origin not in origins:
+                origins.append(origin)
+        return tuple(origins)
+
+    @model_validator(mode="after")
+    def validate_production_contract(self) -> Settings:
+        """Fail clearly when the Docker production boundary is unsafe.
+
+        Local development and tests retain the established SQLite defaults.
+        The production Dockerfile sets ``APP_ENVIRONMENT=production``, making
+        external PostgreSQL, RLS, explicit migrations, authentication, and an
+        exact frontend CORS origin mandatory at process import/startup.
+        """
+
+        origins = self.allowed_cors_origins
+        if self.app_environment != "production":
+            return self
+
+        errors: list[str] = []
+        if not self._is_external_postgres(self.database_url):
+            errors.append("DATABASE_URL must use an external PostgreSQL database in production")
+        if self.security_auto_migrate:
+            errors.append("SECURITY_AUTO_MIGRATE must be false in production")
+        if not self.security_enforce_rls:
+            errors.append("SECURITY_ENFORCE_RLS must be true in production")
+        if not self.security_database_role.strip():
+            errors.append("SECURITY_DATABASE_ROLE is required in production")
+        if not self.auth_enabled:
+            errors.append("AUTH_ENABLED must be true in production")
+        if not origins:
+            errors.append("CORS_ALLOWED_ORIGINS must include the HTTPS Vercel frontend origin")
+        elif any(urlparse(origin).scheme != "https" for origin in origins):
+            errors.append("CORS_ALLOWED_ORIGINS must use HTTPS in production")
+
+        if self.social_auto_migrate:
+            errors.append("SOCIAL_AUTO_MIGRATE must be false in production")
+        if self.social_enabled:
+            if not self.social_database_url.strip() or not self._is_external_postgres(
+                self.social_database_url
+            ):
+                errors.append(
+                    "SOCIAL_DATABASE_URL must use an explicit external PostgreSQL tenant connection"
+                )
+            if not self.social_tenant_database_role.strip():
+                errors.append("SOCIAL_TENANT_DATABASE_ROLE is required when social is enabled")
+            if not self._is_external_postgres(self.social_worker_database_url):
+                errors.append(
+                    "SOCIAL_WORKER_DATABASE_URL must use an external PostgreSQL worker connection"
+                )
+            if not self.social_worker_database_role.strip():
+                errors.append("SOCIAL_WORKER_DATABASE_ROLE is required when social is enabled")
+            if not self.social_enforce_rls:
+                errors.append("SOCIAL_ENFORCE_RLS must be true when social is enabled")
+
+        if errors:
+            raise ValueError("Invalid production configuration: " + "; ".join(errors))
+        return self
+
+    @staticmethod
+    def _is_external_postgres(value: str) -> bool:
+        configured = value.strip()
+        if not configured:
+            return False
+        parsed = urlparse(configured)
+        if parsed.scheme not in {"postgres", "postgresql", "postgresql+asyncpg"}:
+            return False
+        hostname = (parsed.hostname or "").lower()
+        return bool(hostname and hostname not in {"localhost", "127.0.0.1", "::1"})
+
     def ensure_directories(self) -> None:
         self.temp_dir.mkdir(parents=True, exist_ok=True)
         self.output_dir.mkdir(parents=True, exist_ok=True)
@@ -245,9 +388,7 @@ class Settings(BaseSettings):
                 or (parsed.scheme == "http" and parsed.hostname in local_hosts)
             )
         ):
-            raise ValueError(
-                "X_REDIRECT_URI must be the HTTPS MediaRouter X callback URI"
-            )
+            raise ValueError("X_REDIRECT_URI must be the HTTPS MediaRouter X callback URI")
         return normalized
 
     @field_validator("linkedin_redirect_uri")

app/core/database_url.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+
+def normalize_async_database_url(value: str) -> str:
+    """Use the installed asyncpg dialect for bare PostgreSQL URLs.
+
+    Operators frequently supply a standard ``postgresql://`` URL. SQLAlchemy
+    otherwise selects synchronous psycopg2 for that form, which fails inside
+    this async application and can tempt deployments to add an unnecessary
+    synchronous driver. Explicit dialect URLs remain unchanged.
+    """
+
+    normalized = value.strip()
+    if normalized.startswith("postgresql://"):
+        return "postgresql+asyncpg://" + normalized.removeprefix("postgresql://")
+    if normalized.startswith("postgres://"):
+        return "postgresql+asyncpg://" + normalized.removeprefix("postgres://")
+    return normalized

app/generation/__init__.py

@@ -0,0 +1,5 @@
+"""Provider-neutral, durable generation orchestration.
+
+This package contains provider-neutral generation orchestration plus audited,
+optional WAN and FLUX adapters.
+"""

app/generation/domain/__init__.py

@@ -0,0 +1,23 @@
+"""Generation-domain value types, capabilities, and errors."""
+
+from app.generation.domain.enums import (
+    GenerationJobStatus,
+    GenerationModality,
+    GenerationRequestStatus,
+    WorkerCancellationStatus,
+    WorkerErrorCategory,
+    WorkerHealthStatus,
+    WorkerJobStatus,
+    WorkerReadinessStatus,
+)
+
+__all__ = [
+    "GenerationJobStatus",
+    "GenerationModality",
+    "GenerationRequestStatus",
+    "WorkerCancellationStatus",
+    "WorkerErrorCategory",
+    "WorkerHealthStatus",
+    "WorkerJobStatus",
+    "WorkerReadinessStatus",
+]

app/generation/domain/capabilities.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from app.generation.domain.enums import GenerationModality
+
+
+class GenerationModelCapability(BaseModel):
+    """An explicitly implemented model contract.
+
+    ``input_schema`` is descriptive only; request validation remains owned by
+    the adapter's typed Pydantic input model.  It lets future transports build
+    capability-driven UIs without accepting arbitrary provider payloads.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(min_length=1, max_length=255)
+    name: str = Field(min_length=1, max_length=255)
+    modality: GenerationModality
+    input_asset_supported: bool = False
+    input_schema: dict[str, object] = Field(default_factory=dict)
+
+
+class GenerationProviderCapabilities(BaseModel):
+    """Public, non-secret provider discovery metadata."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    provider: str = Field(pattern=r"^[a-z][a-z0-9_-]{0,63}$")
+    name: str = Field(min_length=1, max_length=255)
+    models: list[GenerationModelCapability] = Field(default_factory=list)
+    implementation_status: str = Field(default="foundation", max_length=64)
+    supports_cancellation: bool = False
+    supports_status_reconciliation: bool = False

app/generation/domain/enums.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from app.core.enums import StrEnum
+
+
+class GenerationModality(StrEnum):
+    """Output modalities supported by the foundation.
+
+    The list is intentionally small.  An adapter may only advertise a value
+    after it implements that modality end to end.
+    """
+
+    IMAGE = "image"
+    VIDEO = "video"
+
+
+class GenerationRequestStatus(StrEnum):
+    QUEUED = "queued"
+    SUBMITTING = "submitting"
+    RUNNING = "running"
+    RETRYING = "retrying"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCEL_REQUESTED = "cancel_requested"
+    CANCELLED = "cancelled"
+
+
+class GenerationJobStatus(StrEnum):
+    QUEUED = "queued"
+    SUBMITTING = "submitting"
+    RUNNING = "running"
+    RETRYING = "retrying"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCEL_REQUESTED = "cancel_requested"
+    CANCELLED = "cancelled"
+
+
+class WorkerHealthStatus(StrEnum):
+    HEALTHY = "healthy"
+    STARTING = "starting"
+    UNAVAILABLE = "unavailable"
+    UNHEALTHY = "unhealthy"
+    UNKNOWN = "unknown"
+
+
+class WorkerReadinessStatus(StrEnum):
+    READY = "ready"
+    STARTING = "starting"
+    UNAVAILABLE = "unavailable"
+    UNKNOWN = "unknown"
+
+
+class WorkerJobStatus(StrEnum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    UNKNOWN = "unknown"
+
+
+class WorkerCancellationStatus(StrEnum):
+    REQUESTED = "requested"
+    CANCELLED = "cancelled"
+    UNSUPPORTED = "unsupported"
+    FAILED = "failed"
+
+
+class WorkerErrorCategory(StrEnum):
+    INVALID_REQUEST = "invalid_request"
+    AUTHENTICATION_ERROR = "authentication_error"
+    AUTHORIZATION_ERROR = "authorization_error"
+    WORKER_UNAVAILABLE = "worker_unavailable"
+    WORKER_NOT_READY = "worker_not_ready"
+    TIMEOUT = "timeout"
+    RATE_LIMITED = "rate_limited"
+    PROVIDER_ERROR = "provider_error"
+    INFERENCE_ERROR = "inference_error"
+    OUTPUT_ERROR = "output_error"
+    CANCELLATION_ERROR = "cancellation_error"
+    UNKNOWN_ERROR = "unknown_error"
+
+
+TERMINAL_GENERATION_JOB_STATUSES = frozenset(
+    {
+        GenerationJobStatus.SUCCEEDED,
+        GenerationJobStatus.FAILED,
+        GenerationJobStatus.CANCELLED,
+    }
+)